Passaggio a UTF-8 dei sorgenti
[gapil.git] / sockctrl.tex
1 %% sockctrl.tex
2 %%
3 %% Copyright (C) 2004-2011 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
12 \chapter{La gestione dei socket}
13 \label{cha:sock_generic_management}
14
15 Esamineremo in questo capitolo una serie di funzionalità aggiuntive relative
16 alla gestione dei socket, come la gestione della risoluzione di nomi e
17 indirizzi, le impostazioni delle varie proprietà ed opzioni relative ai
18 socket, e le funzioni di controllo che permettono di modificarne il
19 comportamento.
20
21
22 \section{La risoluzione dei nomi}
23 \label{sec:sock_name_resolution}
24
25 Negli esempi dei capitoli precedenti abbiamo sempre identificato le singole
26 macchine attraverso indirizzi numerici, sfruttando al più le funzioni di
27 conversione elementare illustrate in sez.~\ref{sec:sock_addr_func} che
28 permettono di passare da un indirizzo espresso in forma \textit{dotted
29   decimal} ad un numero. Vedremo in questa sezione le funzioni utilizzate per
30 poter utilizzare dei nomi simbolici al posto dei valori numerici, e viceversa
31 quelle che permettono di ottenere i nomi simbolici associati ad indirizzi,
32 porte o altre proprietà del sistema.
33
34
35 \subsection{La struttura del \textit{resolver}}
36 \label{sec:sock_resolver}
37
38 \itindbeg{resolver}
39 La risoluzione dei nomi è associata tradizionalmente al servizio del
40 \textit{Domain Name Service} che permette di identificare le macchine su
41 internet invece che per numero IP attraverso il relativo \textsl{nome a
42   dominio}.\footnote{non staremo ad entrare nei dettagli della definizione di
43   cosa è un nome a dominio, dandolo per noto, una introduzione alla
44   problematica si trova in \cite{AGL} (cap.~9) mentre per una trattazione
45   approfondita di tutte le problematiche relative al DNS si può fare
46   riferimento a \cite{DNSbind}.} In realtà per DNS si intendono spesso i
47 server che forniscono su internet questo servizio, mentre nel nostro caso
48 affronteremo la problematica dal lato client, di un qualunque programma che
49 necessita di compiere questa operazione.
50
51 \begin{figure}[htb]
52   \centering
53   \includegraphics[width=11cm]{img/resolver}
54   \caption{Schema di funzionamento delle funzioni del \textit{resolver}.}
55   \label{fig:sock_resolver_schema}
56 \end{figure}
57
58 Inoltre quella fra nomi a dominio e indirizzi IP non è l'unica corrispondenza
59 possibile fra nomi simbolici e valori numerici, come abbiamo visto anche in
60 sez.~\ref{sec:sys_user_group} per le corrispondenze fra nomi di utenti e
61 gruppi e relativi identificatori numerici; per quanto riguarda però tutti i
62 nomi associati a identificativi o servizi relativi alla rete il servizio di
63 risoluzione è gestito in maniera unificata da un insieme di funzioni fornite
64 con le librerie del C, detto appunto \textit{resolver}.
65
66 Lo schema di funzionamento del \textit{resolver} è illustrato in
67 fig.~\ref{fig:sock_resolver_schema}; in sostanza i programmi hanno a
68 disposizione un insieme di funzioni di libreria con cui chiamano il
69 \textit{resolver}, indicate con le frecce nere. Ricevuta la richiesta è
70 quest'ultimo che, sulla base della sua configurazione, esegue le operazioni
71 necessarie a fornire la risposta, che possono essere la lettura delle
72 informazioni mantenute nei relativi dei file statici presenti sulla macchina,
73 una interrogazione ad un DNS (che a sua volta, per il funzionamento del
74 protocollo, può interrogarne altri) o la richiesta ad altri server per i quali
75 sia fornito il supporto, come LDAP.\footnote{la sigla LDAP fa riferimento ad
76   un protocollo, il \textit{Lightweight Directory Access Protocol}, che
77   prevede un meccanismo per la gestione di \textsl{elenchi} di informazioni
78   via rete; il contenuto di un elenco può essere assolutamente generico, e
79   questo permette il mantenimento dei più vari tipi di informazioni su una
80   infrastruttura di questo tipo.}
81
82 La configurazione del \textit{resolver} attiene più alla amministrazione di
83 sistema che alla programmazione, ciò non di meno, prima di trattare le varie
84 funzioni di librerie utilizzate dai programmi, vale la pena fare una
85 panoramica generale.  Originariamente la configurazione del \textit{resolver}
86 riguardava esclusivamente le questioni relative alla gestione dei nomi a
87 dominio, e prevedeva solo l'utilizzo del DNS e del file statico
88 \conffile{/etc/hosts}.
89
90 Per questo aspetto il file di configurazione principale del sistema è
91 \conffile{/etc/resolv.conf} che contiene in sostanza l'elenco degli indirizzi
92 IP dei server DNS da contattare; a questo si affianca il file
93 \conffile{/etc/host.conf} il cui scopo principale è indicare l'ordine in cui
94 eseguire la risoluzione dei nomi (se usare prima i valori di
95 \conffile{/etc/hosts} o quelli del DNS). Tralasciamo i dettagli relativi alle
96 varie direttive che possono essere usate in questi file, che si trovano nelle
97 rispettive pagine di manuale.
98
99 Con il tempo però è divenuto possibile fornire diversi sostituti per
100 l'utilizzo delle associazione statiche in \conffile{/etc/hosts}, inoltre oltre
101 alla risoluzione dei nomi a dominio ci sono anche altri nomi da risolvere,
102 come quelli che possono essere associati ad una rete (invece che ad una
103 singola macchina) o ai gruppi di macchine definiti dal servizio
104 NIS,\footnote{il \textit{Network Information Service} è un servizio, creato da
105   Sun, e poi diffuso su tutte le piattaforme unix-like, che permette di
106   raggruppare all'interno di una rete (in quelli che appunto vengono chiamati
107   \textit{netgroup}) varie macchine, centralizzando i servizi di definizione
108   di utenti e gruppi e di autenticazione, oggi è sempre più spesso sostituito
109   da LDAP.} o come quelli dei protocolli e dei servizi che sono mantenuti nei
110 file statici \conffile{/etc/protocols} e \conffile{/etc/services}.  Molte di
111 queste informazioni non si trovano su un DNS, ma in una rete locale può essere
112 molto utile centralizzare il mantenimento di alcune di esse su opportuni
113 server.  Inoltre l'uso di diversi supporti possibili per le stesse
114 informazioni (ad esempio il nome delle macchine può essere mantenuto sia
115 tramite \conffile{/etc/hosts}, che con il DNS, che con NIS) comporta il
116 problema dell'ordine in cui questi vengono interrogati.\footnote{con le
117   implementazioni classiche i vari supporti erano introdotti modificando
118   direttamente le funzioni di libreria, prevedendo un ordine di interrogazione
119   predefinito e non modificabile (a meno di una ricompilazione delle librerie
120   stesse).}
121
122 \itindbeg{Name~Service~Switch}
123 Per risolvere questa serie di problemi la risoluzione dei nomi a dominio
124 eseguirà dal \textit{resolver} è stata inclusa all'interno di un meccanismo
125 generico per la risoluzione di corrispondenze fra nomi ed informazioni ad essi
126 associate chiamato \textit{Name Service Switch}\footnote{il sistema è stato
127   introdotto la prima volta nelle librerie standard di Solaris, le \acr{glibc}
128   hanno ripreso lo stesso schema, si tenga presente che questo sistema non
129   esiste per altre librerie standard come le \acr{libc5} o le \acr{uclib}.}
130 cui abbiamo accennato anche in sez.~\ref{sec:sys_user_group} per quanto
131 riguarda la gestione dei dati associati a utenti e gruppi.  Il \textit{Name
132   Service Switch} (cui spesso si fa riferimento con l'acronimo NSS) è un
133 sistema di librerie dinamiche che permette di definire in maniera generica sia
134 i supporti su cui mantenere i dati di corrispondenza fra nomi e valori
135 numerici, sia l'ordine in cui effettuare le ricerche sui vari supporti
136 disponibili. Il sistema prevede una serie di possibili classi di
137 corrispondenza, quelle attualmente definite sono riportate in
138 tab.~\ref{tab:sys_NSS_classes}.
139
140 \begin{table}[htb]
141   \footnotesize
142   \centering
143   \begin{tabular}[c]{|l|p{8cm}|}
144     \hline
145     \textbf{Classe} & \textbf{Tipo di corrispondenza}\\
146     \hline
147     \hline
148     \texttt{passwd}   & Corrispondenze fra nome dell'utente e relative
149                         proprietà (\acr{uid}, gruppo principale, ecc.).\\  
150     \texttt{shadow}   & Corrispondenze fra username e password dell'utente
151                         (e altre informazioni relative alle password).\\  
152     \texttt{group}    & Corrispondenze fra nome del gruppo e proprietà dello 
153                         stesso.\\  
154     \texttt{aliases}  & Alias per la posta elettronica.\\ 
155     \texttt{ethers}   & Corrispondenze fra numero IP e MAC address della
156                         scheda di rete.\\ 
157     \texttt{hosts}    & Corrispondenze fra nome a dominio e numero IP.\\ 
158     \texttt{netgroup} & Corrispondenze fra gruppo di rete e macchine che lo
159                         compongono.\\  
160     \texttt{networks} & Corrispondenze fra nome di una rete e suo indirizzo
161                         IP.\\  
162     \texttt{protocols}& Corrispondenze fra nome di un protocollo e relativo
163                         numero identificativo.\\ 
164     \texttt{rpc}      & Corrispondenze fra nome di un servizio RPC e relativo 
165                         numero identificativo.\\ 
166     \texttt{publickey}& Chiavi pubbliche e private usate per gli RFC sicuri,
167                         utilizzate da NFS e NIS+. \\ 
168     \texttt{services} & Corrispondenze fra nome di un servizio e numero di
169                         porta. \\ 
170     \hline
171   \end{tabular}
172   \caption{Le diverse classi di corrispondenze definite
173     all'interno del \textit{Name Service Switch}.} 
174   \label{tab:sys_NSS_classes}
175 \end{table}
176
177 % TODO rivedere meglio la tabella
178
179 Il sistema del \textit{Name Service Switch} è controllato dal contenuto del
180 file \conffile{/etc/nsswitch.conf}; questo contiene una riga\footnote{seguendo
181   una convezione comune per i file di configurazione le righe vuote vengono
182   ignorate e tutto quello che segue un carattere ``\texttt{\#}'' viene
183   considerato un commento.} di configurazione per ciascuna di queste classi,
184 che viene inizia col nome di tab.~\ref{tab:sys_NSS_classes} seguito da un
185 carattere ``\texttt{:}'' e prosegue con la lista dei \textsl{servizi} su cui
186 le relative informazioni sono raggiungibili, scritti nell'ordine in cui si
187 vuole siano interrogati.
188
189 Ogni servizio è specificato a sua volta da un nome, come \texttt{file},
190 \texttt{dns}, \texttt{db}, ecc.  che identifica la libreria dinamica che
191 realizza l'interfaccia con esso. Per ciascun servizio se \texttt{NAME} è il
192 nome utilizzato dentro \conffile{/etc/nsswitch.conf}, dovrà essere presente
193 (usualmente in \file{/lib}) una libreria \texttt{libnss\_NAME} che ne
194 implementa le funzioni.
195
196 In ogni caso, qualunque sia la modalità con cui ricevono i dati o il supporto
197 su cui vengono mantenuti, e che si usino o meno funzionalità aggiuntive
198 fornire dal sistema del \textit{Name Service Switch}, dal punto di vista di un
199 programma che deve effettuare la risoluzione di un nome a dominio, tutto
200 quello che conta sono le funzioni classiche che il \textit{resolver} mette a
201 disposizione,\footnote{è cura della implementazione fattane nelle \acr{glibc}
202   tenere conto della presenza del \textit{Name Service Switch}.} e sono queste
203 quelle che tratteremo nelle sezioni successive.
204 \itindend{Name~Service~Switch}
205
206
207 \subsection{Le funzioni di interrogazione del \textit{resolver}}
208 \label{sec:sock_resolver_functions}
209
210 Prima di trattare le funzioni usate normalmente nella risoluzione dei nomi a
211 dominio conviene trattare in maniera più dettagliata il meccanismo principale
212 da esse utilizzato e cioè quello del servizio DNS. Come accennato questo,
213 benché in teoria sia solo uno dei possibili supporti su cui mantenere le
214 informazioni, in pratica costituisce il meccanismo principale con cui vengono
215 risolti i nomi a dominio.  Per questo motivo esistono una serie di funzioni di
216 libreria che servono specificamente ad eseguire delle interrogazioni verso un
217 server DNS, funzioni che poi vengono utilizzate per realizzare le funzioni
218 generiche di libreria usate anche dal sistema del \textit{resolver}.
219
220 Il sistema del DNS è in sostanza di un database distribuito organizzato in
221 maniera gerarchica, i dati vengono mantenuti in tanti server distinti ciascuno
222 dei quali si occupa della risoluzione del proprio \textsl{dominio}; i nomi a
223 dominio sono organizzati in una struttura ad albero analoga a quella
224 dell'albero dei file, con domini di primo livello (come i \texttt{.org}),
225 secondo livello (come \texttt{.truelite.it}), ecc.  In questo caso le
226 separazioni sono fra i vari livelli sono definite dal carattere ``\texttt{.}''
227 ed i nomi devono essere risolti da destra verso sinistra.\footnote{per chi si
228   stia chiedendo quale sia la radice di questo albero, cioè l'equivalente di
229   ``\texttt{/}'', la risposta è il dominio speciale ``\texttt{.}'', che in
230   genere non viene mai scritto esplicitamente, ma che, come chiunque abbia
231   configurato un server DNS sa bene, esiste ed è gestito dai cosiddetti
232   \textit{root DNS} che risolvono i domini di primo livello.} Il meccanismo
233 funziona con il criterio della \textsl{delegazione}, un server responsabile
234 per un dominio di primo livello può delegare la risoluzione degli indirizzi
235 per un suo dominio di secondo livello ad un altro server, il quale a sua volta
236 potrà delegare la risoluzione di un eventuale sotto-dominio di terzo livello ad
237 un altro server ancora.
238
239 In realtà un server DNS è in grado di fare altro rispetto alla risoluzione di
240 un nome a dominio in un indirizzo IP; ciascuna voce nel database viene
241 chiamata \textit{resource record}, e può contenere diverse informazioni. In
242 genere i \textit{resource record} vengono classificati per la \textsl{classe
243   di indirizzi} cui i dati contenuti fanno riferimento, e per il \textsl{tipo}
244 di questi ultimi.\footnote{ritroveremo classi di indirizzi e tipi di record
245   più avanti in tab.~\ref{tab:DNS_address_class} e
246   tab.~\ref{tab:DNS_record_type}.}  Oggigiorno i dati mantenuti nei server DNS
247 sono quasi esclusivamente relativi ad indirizzi internet, per cui in pratica
248 viene utilizzata soltanto una classe di indirizzi; invece le corrispondenze
249 fra un nome a dominio ed un indirizzo IP sono solo uno fra i vari tipi di
250 informazione che un server DNS fornisce normalmente.
251
252 L'esistenza di vari tipi di informazioni è un altro dei motivi per cui il
253 \textit{resolver} prevede, rispetto a quelle relative alla semplice
254 risoluzione dei nomi, un insieme di funzioni specifiche dedicate
255 all'interrogazione di un server DNS; la prima di queste funzioni è
256 \funcd{res\_init}, il cui prototipo è:
257 \begin{functions}
258   \headdecl{netinet/in.h} \headdecl{arpa/nameser.h} \headdecl{resolv.h}
259   \funcdecl{int res\_init(void)}
260
261 Inizializza il sistema del \textit{resolver}.
262
263 \bodydesc{La funzione restituisce 0 in caso di successo e -1 in caso di
264   errore.}
265 \end{functions}
266
267 La funzione legge il contenuto dei file di configurazione (i già citati
268 \file{resolv.conf} e \file{host.conf}) per impostare il dominio di default,
269 gli indirizzi dei server DNS da contattare e l'ordine delle ricerche; se non
270 sono specificati server verrà utilizzato l'indirizzo locale, e se non è
271 definito un dominio di default sarà usato quello associato con l'indirizzo
272 locale (ma questo può essere sovrascritto con l'uso della variabile di
273 ambiente \texttt{LOCALDOMAIN}). In genere non è necessario eseguire questa
274 funzione direttamente in quanto viene automaticamente chiamata la prima volta
275 che si esegue una delle altre.
276
277 Le impostazioni e lo stato del \textit{resolver} vengono mantenuti in una
278 serie di variabili raggruppate nei campi di una apposita struttura \var{\_res}
279 usata da tutte queste funzioni. Essa viene definita in \file{resolv.h} ed è
280 utilizzata internamente alle funzioni essendo definita come variabile globale;
281 questo consente anche di accedervi direttamente all'interno di un qualunque
282 programma, una volta che la sia opportunamente dichiarata come:
283 \includecodesnip{listati/resolv_option.c}
284
285 Tutti i campi della struttura sono ad uso interno, e vengono usualmente
286 inizializzati da \func{res\_init} in base al contenuto dei file di
287 configurazione e ad una serie di valori di default. L'unico campo che può
288 essere utile modificare è \var{\_res.options}, una maschera binaria che
289 contiene una serie di bit di opzione che permettono di controllare il
290 comportamento del \textit{resolver}. 
291
292 \begin{table}[htb]
293   \centering
294   \footnotesize
295   \begin{tabular}[c]{|l|p{8cm}|}
296     \hline
297     \textbf{Costante} & \textbf{Significato} \\
298     \hline
299     \hline
300     \const{RES\_INIT}       & Viene attivato se è stata chiamata
301                               \func{res\_init}. \\
302     \const{RES\_DEBUG}      & Stampa dei messaggi di debug.\\
303     \const{RES\_AAONLY}     & Accetta solo risposte autoritative.\\
304     \const{RES\_USEVC}      & Usa connessioni TCP per contattare i server 
305                               invece che l'usuale UDP.\\
306     \const{RES\_PRIMARY}    & Interroga soltanto server DNS primari.
307                               \\
308     \const{RES\_IGNTC}      & Ignora gli errori di troncamento, non ritenta la
309                               richiesta con una connessione TCP.\\
310     \const{RES\_RECURSE}    & Imposta il bit che indica che si desidera
311                               eseguire una interrogazione ricorsiva.\\
312     \const{RES\_DEFNAMES}   & Se attivo \func{res\_search} aggiunge il nome
313                               del dominio di default ai nomi singoli (che non
314                               contengono cioè un ``\texttt{.}'').\\
315     \const{RES\_STAYOPEN}   & Usato con \const{RES\_USEVC} per mantenere
316                               aperte le connessioni TCP fra interrogazioni
317                               diverse. \\
318     \const{RES\_DNSRCH}     & Se attivo \func{res\_search} esegue le ricerche
319                               di nomi di macchine nel dominio corrente o nei
320                               domini ad esso sovrastanti.\\
321     \const{RES\_INSECURE1}  & Blocca i controlli di sicurezza di tipo 1.\\
322     \const{RES\_INSECURE2}  & Blocca i controlli di sicurezza di tipo 2.\\
323     \const{RES\_NOALIASES}  & Blocca l'uso della variabile di ambiente
324                               \texttt{HOSTALIASES}.\\ 
325     \const{RES\_USE\_INET6} & Restituisce indirizzi IPv6 con
326                               \func{gethostbyname}. \\
327     \const{RES\_ROTATE}     & Ruota la lista dei server DNS dopo ogni
328                               interrogazione.\\
329     \const{RES\_NOCHECKNAME}& Non controlla i nomi per verificarne la
330                               correttezza sintattica. \\
331     \const{RES\_KEEPTSIG}   & Non elimina i record di tipo \texttt{TSIG}.\\
332     \const{RES\_BLAST}      & Effettua un ``\textit{blast}'' inviando
333                               simultaneamente le richieste a tutti i server;
334                               non ancora implementata. \\
335     \const{RES\_DEFAULT}    & Combinazione di \const{RES\_RECURSE},
336                               \const{RES\_DEFNAMES} e \const{RES\_DNSRCH}.\\
337     \hline
338   \end{tabular}
339   \caption{Costanti utilizzabili come valori per \var{\_res.options}.}
340   \label{tab:resolver_option}
341 \end{table}
342
343 Per utilizzare questa funzionalità per modificare le impostazioni direttamente
344 da programma occorrerà impostare un opportuno valore per questo campo ed
345 invocare esplicitamente \func{res\_init}, dopo di che le altre funzioni
346 prenderanno le nuove impostazioni. Le costanti che definiscono i vari bit di
347 questo campo, ed il relativo significato sono illustrate in
348 tab.~\ref{tab:resolver_option}; trattandosi di una maschera binaria un valore
349 deve essere espresso con un opportuno OR aritmetico di dette costanti; ad
350 esempio il valore di default delle opzioni, espresso dalla costante
351 \const{RES\_DEFAULT}, è definito come:
352 \includecodesnip{listati/resolv_option_def.c}
353
354 Non tratteremo il significato degli altri campi non essendovi necessità di
355 modificarli direttamente; gran parte di essi sono infatti impostati dal
356 contenuto dei file di configurazione, mentre le funzionalità controllate da
357 alcuni di esse possono essere modificate con l'uso delle opportune variabili
358 di ambiente come abbiamo visto per \texttt{LOCALDOMAIN}. In particolare con
359 \texttt{RES\_RETRY} si soprassiede il valore del campo \var{retry} che
360 controlla quante volte viene ripetuto il tentativo di connettersi ad un server
361 DNS prima di dichiarare fallimento; il valore di default è 4, un valore nullo
362 significa bloccare l'uso del DNS. Infine con \texttt{RES\_TIMEOUT} si
363 soprassiede il valore del campo \var{retrans},\footnote{preimpostato al valore
364   della omonima costante \const{RES\_TIMEOUT} di \file{resolv.h}.} che è il
365 valore preso come base (in numero di secondi) per definire la scadenza di una
366 richiesta, ciascun tentativo di richiesta fallito viene ripetuto raddoppiando
367 il tempo di scadenza per il numero massimo di volte stabilito da
368 \texttt{RES\_RETRY}.
369
370 La funzione di interrogazione principale è \funcd{res\_query}, che serve ad
371 eseguire una richiesta ad un server DNS per un nome a dominio
372 \textsl{completamente specificato} (quello che si chiama FQDN, \textit{Fully
373   Qualified Domain Name}); il suo prototipo è:
374
375 \begin{functions}
376 \headdecl{netinet/in.h}
377 \headdecl{arpa/nameser.h}
378 \headdecl{resolv.h}
379 \funcdecl{int res\_query(const char *dname, int class, int type,
380               unsigned char *answer, int anslen)}
381
382   Esegue una interrogazione al DNS.
383
384 \bodydesc{La funzione restituisce un valore positivo pari alla lunghezza dei
385     dati scritti nel buffer \param{answer} in caso di successo e -1 in caso di
386     errore.}
387 \end{functions}
388
389 La funzione esegue una interrogazione ad un server DNS relativa al nome da
390 risolvere passato nella stringa indirizzata da \param{dname}, inoltre deve
391 essere specificata la classe di indirizzi in cui eseguire la ricerca con
392 \param{class}, ed il tipo di \textit{resource record} che si vuole ottenere
393 con \param{type}. Il risultato della ricerca verrà scritto nel buffer di
394 lunghezza \param{anslen} puntato da \param{answer} che si sarà opportunamente
395 allocato in precedenza.
396
397
398 Una seconda funzione di ricerca, analoga a \func{res\_query}, che prende gli
399 stessi argomenti, ma che esegue l'interrogazione con le funzionalità
400 addizionali previste dalle due opzioni \const{RES\_DEFNAMES} e
401 \const{RES\_DNSRCH}, è \funcd{res\_search}, il cui prototipo è:
402 \begin{functions}
403 \headdecl{netinet/in.h}
404 \headdecl{arpa/nameser.h}
405 \headdecl{resolv.h}
406 \funcdecl{int res\_search(const char *dname, int class, int type,
407               unsigned char *answer, int anslen)}
408
409   Esegue una interrogazione al DNS.
410   
411   \bodydesc{La funzione restituisce un valore positivo pari alla lunghezza dei
412     dati scritti nel buffer \param{answer} in caso di successo e -1 in caso di
413     errore.}
414 \end{functions}
415
416 In sostanza la funzione ripete una serie di chiamate a \func{res\_query}
417 aggiungendo al nome contenuto nella stringa \param{dname} il dominio di
418 default da cercare, fermandosi non appena trova un risultato.  Il risultato di
419 entrambe le funzioni viene scritto nel formato opportuno (che sarà diverso a
420 seconda del tipo di record richiesto) nel buffer di ritorno; sarà compito del
421 programma (o di altre funzioni) estrarre i relativi dati, esistono una serie
422 di funzioni interne usate per la scansione di questi dati, per chi fosse
423 interessato una trattazione dettagliata è riportata nel quattordicesimo
424 capitolo di \cite{DNSbind}.
425
426 Le classi di indirizzi supportate da un server DNS sono tre, ma di queste in
427 pratica oggi viene utilizzata soltanto quella degli indirizzi internet; le
428 costanti che identificano dette classi, da usare come valore per l'argomento
429 \param{class} delle precedenti funzioni, sono riportate in
430 tab.~\ref{tab:DNS_address_class}.\footnote{esisteva in realtà anche una classe
431   \const{C\_CSNET} per la omonima rete, ma è stata dichiarata obsoleta.}
432
433 \begin{table}[htb]
434   \centering
435   \footnotesize
436   \begin{tabular}[c]{|l|p{8cm}|}
437     \hline
438     \textbf{Costante} & \textbf{Significato} \\
439     \hline
440     \hline
441     \const{C\_IN}   & Indirizzi internet, in pratica i soli utilizzati oggi.\\
442     \const{C\_HS}   & Indirizzi \textit{Hesiod}, utilizzati solo al MIT, oggi
443                       completamente estinti. \\
444     \const{C\_CHAOS}& Indirizzi per la rete \textit{Chaosnet}, un'altra rete
445                       sperimentale nata al MIT. \\
446     \const{C\_ANY}  & Indica un indirizzo di classe qualunque.\\
447     \hline
448   \end{tabular}
449   \caption{Costanti identificative delle classi di indirizzi per l'argomento
450     \param{class} di \func{res\_query}.}
451   \label{tab:DNS_address_class}
452 \end{table}
453
454 Come accennato le tipologie di dati che sono mantenibili su un server DNS sono
455 diverse, ed a ciascuna di essa corrisponde un diverso tipo di \textit{resource
456   record}. L'elenco delle costanti\footnote{ripreso dai file di dichiarazione
457   \file{arpa/nameser.h} e \file{arpa/nameser\_compat.h}.} che definiscono i
458 valori che si possono usare per l'argomento \param{type} per specificare il
459 tipo di \textit{resource record} da richiedere è riportato in
460 tab.~\ref{tab:DNS_record_type}; le costanti (tolto il \texttt{T\_} iniziale)
461 hanno gli stessi nomi usati per identificare i record nei file di zona di
462 BIND,\footnote{BIND, acronimo di \textit{Berkley Internet Name Domain}, è una
463   implementazione di un server DNS, ed, essendo utilizzata nella stragrande
464   maggioranza dei casi, fa da riferimento; i dati relativi ad un certo
465   dominio (cioè i suoi \textit{resource record} vengono mantenuti in quelli
466   che sono usualmente chiamati \textsl{file di zona}, e in essi ciascun tipo
467   di dominio è identificato da un nome che è appunto identico a quello delle
468   costanti di tab.~\ref{tab:DNS_record_type} senza il \texttt{T\_} iniziale.}
469 e che normalmente sono anche usati come nomi per indicare i record.
470
471 \begin{table}[!htb]
472   \centering
473   \footnotesize
474   \begin{tabular}[c]{|l|l|}
475     \hline
476     \textbf{Costante} & \textbf{Significato} \\
477     \hline
478     \hline
479     \const{T\_A}     & Indirizzo di una stazione.\\
480     \const{T\_NS}    & Server DNS autoritativo per il dominio richiesto.\\
481     \const{T\_MD}    & Destinazione per la posta elettronica.\\
482     \const{T\_MF}    & Redistributore per la posta elettronica.\\
483     \const{T\_CNAME} & Nome canonico.\\
484     \const{T\_SOA}   & Inizio di una zona di autorità.\\
485     \const{T\_MB}    & Nome a dominio di una casella di posta.\\
486     \const{T\_MG}    & Nome di un membro di un gruppo di posta.\\
487     \const{T\_MR}    & Nome di un cambiamento di nome per la posta.\\
488     \const{T\_NULL}  & Record nullo.\\
489     \const{T\_WKS}   & Servizio noto.\\
490     \const{T\_PTR}   & Risoluzione inversa di un indirizzo numerico.\\
491     \const{T\_HINFO} & Informazione sulla stazione.\\
492     \const{T\_MINFO} & Informazione sulla casella di posta.\\
493     \const{T\_MX}    & Server cui instradare la posta per il dominio.\\
494     \const{T\_TXT}   & Stringhe di testo (libere).\\
495     \const{T\_RP}    & Nome di un responsabile (\textit{responsible person}).\\
496     \const{T\_AFSDB} & Database per una cella AFS.\\
497     \const{T\_X25}   & Indirizzo di chiamata per X.25.\\
498     \const{T\_ISDN}  & Indirizzo di chiamata per ISDN.\\
499     \const{T\_RT}    & Router.\\
500     \const{T\_NSAP}  & Indirizzo NSAP.\\
501     \const{T\_NSAP\_PTR}& Risoluzione inversa per NSAP (deprecato).\\
502     \const{T\_SIG}   & Firma digitale di sicurezza.\\
503     \const{T\_KEY}   & Chiave per firma.\\
504     \const{T\_PX}    & Corrispondenza per la posta X.400.\\
505     \const{T\_GPOS}  & Posizione geografica.\\
506     \const{T\_AAAA}  & Indirizzo IPv6.\\
507     \const{T\_LOC}   & Informazione di collocazione.\\
508     \const{T\_NXT}   & Dominio successivo.\\
509     \const{T\_EID}   & Identificatore di punto conclusivo.\\
510     \const{T\_NIMLOC}& Posizionatore \textit{nimrod}.\\
511     \const{T\_SRV}   & Servizio.\\
512     \const{T\_ATMA}  & Indirizzo ATM.\\
513     \const{T\_NAPTR} & Puntatore ad una \textit{naming authority}.\\
514     \const{T\_TSIG}  & Firma di transazione.\\
515     \const{T\_IXFR}  & Trasferimento di zona incrementale.\\
516     \const{T\_AXFR}  & Trasferimento di zona di autorità.\\
517     \const{T\_MAILB} & Trasferimento di record di caselle di posta.\\
518     \const{T\_MAILA} & Trasferimento di record di server di posta.\\
519     \const{T\_ANY}   & Valore generico.\\
520     \hline
521   \end{tabular}
522   \caption{Costanti identificative del tipo di record per l'argomento
523     \param{type} di \func{res\_query}.}
524   \label{tab:DNS_record_type}
525 \end{table}
526
527
528 L'elenco di tab.~\ref{tab:DNS_record_type} è quello di \textsl{tutti} i
529 \textit{resource record} definiti, con una breve descrizione del relativo
530 significato.  Di tutti questi però viene impiegato correntemente solo un
531 piccolo sottoinsieme, alcuni sono obsoleti ed altri fanno riferimento a dati
532 applicativi che non ci interessano non avendo nulla a che fare con la
533 risoluzione degli indirizzi IP, pertanto non entreremo nei dettagli del
534 significato di tutti i \textit{resource record}, ma solo di quelli usati dalle
535 funzioni del \textit{resolver}. Questi sono sostanzialmente i seguenti (per
536 indicarli si è usata la notazione dei file di zona di BIND):
537 \begin{basedescript}{\desclabelwidth{1.2cm}\desclabelstyle{\nextlinelabel}}
538 \item[\texttt{A}] viene usato per indicare la corrispondenza fra un nome a
539   dominio ed un indirizzo IPv4; ad esempio la corrispondenza fra
540   \texttt{dodds.truelite.it} e l'indirizzo IP \texttt{62.48.34.25}.
541 \item[\texttt{AAAA}] viene usato per indicare la corrispondenza fra un nome a
542   dominio ed un indirizzo IPv6; è chiamato in questo modo dato che la
543   dimensione di un indirizzo IPv6 è quattro volte quella di un indirizzo IPv4.
544 \item[\texttt{PTR}] per fornire la corrispondenza inversa fra un indirizzo IP
545   ed un nome a dominio ad esso associato si utilizza questo tipo di record (il
546   cui nome sta per \textit{pointer}).
547 \item[\texttt{CNAME}] qualora si abbiamo più nomi che corrispondono allo
548   stesso indirizzo (come ad esempio \texttt{www.truelite.it} e
549   \texttt{sources.truelite.it}, che fanno entrambi riferimento alla stessa
550   macchina (nel caso \texttt{dodds.truelite.it}) si può usare questo tipo di
551   record per creare degli \textit{alias} in modo da associare un qualunque
552   altro nome al \textsl{nome canonico} della macchina (si chiama così quello
553   associato al record \texttt{A}).
554 \end{basedescript}
555
556 Come accennato in caso di successo le due funzioni di richiesta restituiscono
557 il risultato della interrogazione al server, in caso di insuccesso l'errore
558 invece viene segnalato da un valore di ritorno pari a -1, ma in questo caso,
559 non può essere utilizzata la variabile \var{errno} per riportare un codice di
560 errore, in quanto questo viene impostato per ciascuna delle chiamate al
561 sistema utilizzate dalle funzioni del \textit{resolver}, non avrà alcun
562 significato nell'indicare quale parte del procedimento di risoluzione è
563 fallita.
564
565 Per questo motivo è stata definita una variabile di errore separata,
566 \var{h\_errno}, che viene utilizzata dalle funzioni del \textit{resolver} per
567 indicare quale problema ha causato il fallimento della risoluzione del nome.
568 Ad essa si può accedere una volta che la si dichiara con:
569 \includecodesnip{listati/herrno.c} 
570 ed i valori che può assumere, con il relativo significato, sono riportati in
571 tab.~\ref{tab:h_errno_values}.
572
573 \begin{table}[!htb]
574   \centering
575   \footnotesize
576   \begin{tabular}[c]{|l|p{11cm}|}
577     \hline
578     \textbf{Costante} & \textbf{Significato} \\
579     \hline
580     \hline
581     \const{HOST\_NOT\_FOUND} & L'indirizzo richiesto non è valido e la
582                                macchina indicata è sconosciuta.\\
583     \const{NO\_ADDRESS}      & Il nome a dominio richiesto è valido, ma non ha
584                                un indirizzo associato ad esso
585                                (alternativamente può essere indicato come 
586                                \const{NO\_DATA}).\\
587     \const{NO\_RECOVERY}     & Si è avuto un errore non recuperabile
588                                nell'interrogazione di un server DNS.\\
589     \const{TRY\_AGAIN}       & Si è avuto un errore temporaneo
590                                nell'interrogazione di un server DNS, si può
591                                ritentare l'interrogazione in un secondo
592                                tempo.\\
593     \hline
594   \end{tabular}
595   \caption{Valori possibili della variabile \var{h\_errno}.}
596   \label{tab:h_errno_values}
597 \end{table}
598
599 Insieme alla nuova variabile vengono definite anche due nuove funzioni per
600 stampare l'errore a video, analoghe a quelle di sez.~\ref{sec:sys_strerror}
601 per \var{errno}, ma che usano il valore di \var{h\_errno}; la prima è
602 \funcd{herror} ed il suo prototipo è:
603 \begin{functions}
604 \headdecl{netdb.h}
605 \funcdecl{void herror(const char *string)}
606
607 Stampa un errore di risoluzione.
608 \end{functions}
609
610 La funzione è l'analoga di \func{perror} e stampa sullo standard error un
611 messaggio di errore corrispondente al valore corrente di \var{h\_errno}, a cui
612 viene anteposta la stringa \param{string} passata come argomento.  La seconda
613 funzione è \funcd{hstrerror} ed il suo prototipo è:
614 \begin{functions}
615 \headdecl{netdb.h}
616 \funcdecl{const char *hstrerror(int err)}
617
618 Restituisce una stringa corrispondente ad un errore di risoluzione.
619 \end{functions}
620 \noindent che, come  l'analoga \func{strerror}, restituisce una stringa con un
621 messaggio di errore già formattato, corrispondente al codice passato come
622 argomento (che si presume sia dato da \var{h\_errno}).
623
624 \itindend{resolver}
625
626
627 \subsection{La risoluzione dei nomi a dominio}
628 \label{sec:sock_name_services}
629
630 La principale funzionalità del \itindex{resolver} \textit{resolver} resta
631 quella di risolvere i nomi a dominio in indirizzi IP, per cui non ci
632 dedicheremo oltre alle funzioni di richiesta generica ed esamineremo invece le
633 funzioni a questo dedicate. La prima funzione è \funcd{gethostbyname} il cui
634 scopo è ottenere l'indirizzo di una stazione noto il suo nome a dominio, il
635 suo prototipo è:
636 \begin{prototype}{netdb.h}
637 {struct hostent *gethostbyname(const char *name)}
638
639 Determina l'indirizzo associato al nome a dominio \param{name}.
640
641 \bodydesc{La funzione restituisce in caso di successo il puntatore ad una
642   struttura di tipo \struct{hostent} contenente i dati associati al nome a
643   dominio, o un puntatore nullo in caso di errore.}
644 \end{prototype}
645
646 La funzione prende come argomento una stringa \param{name} contenente il nome
647 a dominio che si vuole risolvere, in caso di successo i dati ad esso relativi
648 vengono memorizzati in una opportuna struttura \struct{hostent} la cui
649 definizione è riportata in fig.~\ref{fig:sock_hostent_struct}. 
650
651 \begin{figure}[!htb]
652   \footnotesize \centering
653   \begin{minipage}[c]{15cm}
654     \includestruct{listati/hostent.h}
655   \end{minipage}
656   \caption{La struttura \structd{hostent} per la risoluzione dei nomi a
657     dominio e degli indirizzi IP.}
658   \label{fig:sock_hostent_struct}
659 \end{figure}
660
661 Quando un programma chiama \func{gethostbyname} e questa usa il DNS per
662 effettuare la risoluzione del nome, è con i valori contenuti nei relativi
663 record che vengono riempite le varie parti della struttura \struct{hostent}.
664 Il primo campo della struttura, \var{h\_name} contiene sempre il \textsl{nome
665   canonico}, che nel caso del DNS è appunto il nome associato ad un record
666 \texttt{A}. Il secondo campo della struttura, \var{h\_aliases}, invece è un
667 puntatore ad vettore di puntatori, terminato da un puntatore nullo. Ciascun
668 puntatore del vettore punta ad una stringa contenente uno degli altri
669 possibili nomi associati allo stesso \textsl{nome canonico} (quelli che nel
670 DNS vengono inseriti come record di tipo \texttt{CNAME}).
671
672 Il terzo campo della struttura, \var{h\_addrtype}, indica il tipo di indirizzo
673 che è stato restituito, e può assumere soltanto i valori \const{AF\_INET} o
674 \const{AF\_INET6}, mentre il quarto campo, \var{h\_length}, indica la
675 lunghezza dell'indirizzo stesso in byte. 
676
677 Infine il campo \var{h\_addr\_list} è il puntatore ad un vettore di puntatori
678 ai singoli indirizzi; il vettore è terminato da un puntatore nullo.  Inoltre,
679 come illustrato in fig.~\ref{fig:sock_hostent_struct}, viene definito il campo
680 \var{h\_addr} come sinonimo di \code{h\_addr\_list[0]}, cioè un riferimento
681 diretto al primo indirizzo della lista.
682
683 Oltre ai normali nomi a dominio la funzione accetta come argomento
684 \param{name} anche indirizzi numerici, in formato dotted decimal per IPv4 o
685 con la notazione illustrata in sez.~\ref{sec:IP_ipv6_notation} per IPv6. In
686 tal caso \func{gethostbyname} non eseguirà nessuna interrogazione remota, ma
687 si limiterà a copiare la stringa nel campo \var{h\_name} ed a creare la
688 corrispondente struttura \var{in\_addr} da indirizzare con
689 \code{h\_addr\_list[0]}.
690
691 Con l'uso di \func{gethostbyname} normalmente si ottengono solo gli indirizzi
692 IPv4, se si vogliono ottenere degli indirizzi IPv6 occorrerà prima impostare
693 l'opzione \const{RES\_USE\_INET6} nel campo \texttt{\_res.options} e poi
694 chiamare \func{res\_init} (vedi sez.~\ref{sec:sock_resolver_functions}) per
695 modificare le opzioni del \itindex{resolver} \textit{resolver}; dato che
696 questo non è molto comodo è stata definita\footnote{questa è una estensione
697   fornita dalle \acr{glibc}, disponibile anche in altri sistemi unix-like.}
698 un'altra funzione, \funcd{gethostbyname2}, il cui prototipo è:
699 \begin{functions}
700   \headdecl{netdb.h} 
701   \headdecl{sys/socket.h}
702   \funcdecl{struct hostent *gethostbyname2(const char *name, int af)}
703
704 Determina l'indirizzo di tipo \param{af} associato al nome a dominio
705 \param{name}.
706
707 \bodydesc{La funzione restituisce in caso di successo il puntatore ad una
708   struttura di tipo \struct{hostent} contenente i dati associati al nome a
709   dominio, o un puntatore nullo in caso di errore.}
710 \end{functions}
711
712 In questo caso la funzione prende un secondo argomento \param{af} che indica
713 (i soli valori consentiti sono \const{AF\_INET} o \const{AF\_INET6}, per
714 questo è necessario l'uso di \texttt{sys/socket.h}) la famiglia di indirizzi
715 che dovrà essere utilizzata nei risultati restituiti dalla funzione. Per tutto
716 il resto la funzione è identica a \func{gethostbyname}, ed identici sono i
717 suoi risultati.
718
719 \begin{figure}[!htb]
720   \footnotesize \centering
721   \begin{minipage}[c]{15cm}
722     \includecodesample{listati/mygethost.c}
723   \end{minipage}
724   \normalsize
725   \caption{Esempio di codice per la risoluzione di un indirizzo.}
726   \label{fig:mygethost_example}
727 \end{figure}
728
729 Vediamo allora un primo esempio dell'uso delle funzioni di risoluzione, in
730 fig.~\ref{fig:mygethost_example} è riportato un estratto del codice di un
731 programma che esegue una semplice interrogazione al
732 \itindex{resolver} \textit{resolver} usando \func{gethostbyname} e poi ne
733 stampa a video i risultati. Al solito il sorgente completo, che comprende il
734 trattamento delle opzioni ed una funzione per stampare un messaggio di aiuto,
735 è nel file \texttt{mygethost.c} dei sorgenti allegati alla guida.
736
737 Il programma richiede un solo argomento che specifichi il nome da cercare,
738 senza il quale (\texttt{\small 15--18}) esce con un errore. Dopo di che
739 (\texttt{\small 20}) si limita a chiamare \func{gethostbyname}, ricevendo il
740 risultato nel puntatore \var{data}. Questo (\texttt{\small 21--24}) viene
741 controllato per rilevare eventuali errori, nel qual caso il programma esce
742 dopo aver stampato un messaggio con \func{herror}. 
743
744 Se invece la risoluzione è andata a buon fine si inizia (\texttt{\small 25})
745 con lo stampare il nome canonico, dopo di che (\texttt{\small 26--30}) si
746 stampano eventuali altri nomi. Per questo prima (\texttt{\small 26}) si prende
747 il puntatore alla cima della lista che contiene i nomi e poi (\texttt{\small
748   27--30}) si esegue un ciclo che sarà ripetuto fin tanto che nella lista si
749 troveranno dei puntatori validi\footnote{si ricordi che la lista viene
750   terminata da un puntatore nullo.} per le stringhe dei nomi; prima
751 (\texttt{\small 28}) si stamperà la stringa e poi (\texttt{\small 29}) si
752 provvederà ad incrementare il puntatore per passare al successivo elemento
753 della lista.
754
755 Una volta stampati i nomi si passerà a stampare gli indirizzi, il primo passo
756 (\texttt{\small 31--38}) è allora quello di riconoscere il tipo di indirizzo
757 sulla base del valore del campo \var{h\_addrtype}, stampandolo a video. Si è
758 anche previsto di stampare un errore nel caso (che non dovrebbe mai accadere)
759 di un indirizzo non valido.
760
761 Infine (\texttt{\small 39--44}) si stamperanno i valori degli indirizzi, di
762 nuovo (\texttt{\small 39}) si inizializzerà un puntatore alla cima della lista
763 e si eseguirà un ciclo fintanto che questo punterà ad indirizzi validi in
764 maniera analoga a quanto fatto in precedenza per i nomi a dominio. Si noti
765 come, essendo il campo \var{h\_addr\_list} un puntatore ad strutture di
766 indirizzi generiche, questo sia ancora di tipo \texttt{char **} e si possa
767 riutilizzare lo stesso puntatore usato per i nomi.
768
769 Per ciascun indirizzo valido si provvederà (\texttt{\small 41}) ad una
770 conversione con la funzione \func{inet\_ntop} (vedi
771 sez.~\ref{sec:sock_addr_func}) passandole gli opportuni argomenti, questa
772 restituirà la stringa da stampare (\texttt{\small 42}) con il valore
773 dell'indirizzo in \var{buffer}, che si è avuto la cura di dichiarare
774 inizialmente (\texttt{\small 10}) con dimensioni adeguate; dato che la
775 funzione è in grado di tenere conto automaticamente del tipo di indirizzo non
776 ci sono precauzioni particolari da prendere.\footnote{volendo essere pignoli
777   si dovrebbe controllarne lo stato di uscita, lo si è tralasciato per non
778   appesantire il codice, dato che in caso di indirizzi non validi si sarebbe
779   avuto un errore con \func{gethostbyname}, ma si ricordi che la sicurezza non
780   è mai troppa.}
781
782 Le funzioni illustrate finora hanno un difetto: utilizzando una area di
783 memoria interna per allocare i contenuti della struttura \struct{hostent} non
784 possono essere\index{funzioni!rientranti} rientranti. Questo comporta anche
785 che in due successive chiamate i dati potranno essere sovrascritti. Si tenga
786 presente poi che copiare il contenuto della sola struttura non è sufficiente
787 per salvare tutti i dati, in quanto questa contiene puntatori ad altri dati,
788 che pure possono essere sovrascritti; per questo motivo, se si vuole salvare
789 il risultato di una chiamata, occorrerà eseguire quella che si chiama una
790 \itindex{deep~copy} \textit{deep copy}.\footnote{si chiama così quella tecnica
791   per cui, quando si deve copiare il contenuto di una struttura complessa (con
792   puntatori che puntano ad altri dati, che a loro volta possono essere
793   puntatori ad altri dati) si deve copiare non solo il contenuto della
794   struttura, ma eseguire una scansione per risolvere anche tutti i puntatori
795   contenuti in essa (e così via se vi sono altre sotto-strutture con altri
796   puntatori) e copiare anche i dati da questi referenziati.}
797
798 Per ovviare a questi problemi nelle \acr{glibc} sono definite anche delle
799 versioni \index{funzioni!rientranti} rientranti delle precedenti funzioni, al
800 solito queste sono caratterizzate dall'avere un suffisso \texttt{\_r},
801 pertanto avremo le due funzioni \funcd{gethostbyname\_r} e
802 \funcd{gethostbyname2\_r} i cui prototipi sono:
803 \begin{functions}
804   \headdecl{netdb.h} 
805   \headdecl{sys/socket.h}
806   \funcdecl{int gethostbyname\_r(const char *name, struct hostent *ret, 
807     char *buf, size\_t buflen, struct hostent **result, int *h\_errnop)}
808   \funcdecl{int gethostbyname2\_r(const char *name, int af,
809          struct hostent *ret, char *buf, size\_t buflen, 
810          struct hostent **result, int *h\_errnop)}
811   
812   Versioni rientranti delle funzioni \func{gethostbyname} e
813   \func{gethostbyname2}. 
814        
815   \bodydesc{Le funzioni restituiscono 0 in caso di successo ed un valore
816     negativo in caso di errore.}
817 \end{functions}
818
819 Gli argomenti \param{name} (e \param{af} per \func{gethostbyname2\_r}) hanno
820 lo stesso significato visto in precedenza. Tutti gli altri argomenti hanno lo
821 stesso significato per entrambe le funzioni. Per evitare l'uso di variabili
822 globali si dovrà allocare preventivamente una struttura \struct{hostent} in
823 cui ricevere il risultato, passandone l'indirizzo alla funzione nell'argomento
824 \param{ret}.  Inoltre, dato che \struct{hostent} contiene dei puntatori, dovrà
825 essere allocato anche un buffer in cui le funzioni possano scrivere tutti i
826 dati del risultato dell'interrogazione da questi puntati; l'indirizzo e la
827 lunghezza di questo buffer devono essere indicati con gli argomenti
828 \param{buf} e \param{buflen}.
829
830 Gli ultimi due argomenti vengono utilizzati per avere indietro i risultati
831 come \itindex{value~result~argument} \textit{value result argument}, si deve
832 specificare l'indirizzo della variabile su cui la funzione dovrà salvare il
833 codice di errore con \param{h\_errnop} e quello su cui dovrà salvare il
834 puntatore che si userà per accedere i dati con \param{result}.
835
836 In caso di successo entrambe le funzioni restituiscono un valore nullo,
837 altrimenti restituiscono un codice di errore negativo e all'indirizzo puntato
838 da \param{result} sarà salvato un puntatore nullo, mentre a quello puntato da
839 \param{h\_errnop} sarà salvato il valore del codice di errore, dato che per
840 essere \index{funzioni!rientranti} rientrante la funzione non può la variabile
841 globale \var{h\_errno}. In questo caso il codice di errore, oltre ai valori di
842 tab.~\ref{tab:h_errno_values}, può avere anche quello di \errcode{ERANGE}
843 qualora il buffer allocato su \param{buf} non sia sufficiente a contenere i
844 dati, in tal caso si dovrà semplicemente ripetere l'esecuzione della funzione
845 con un buffer di dimensione maggiore.
846
847 Una delle caratteristiche delle interrogazioni al servizio DNS è che queste
848 sono normalmente eseguite con il protocollo UDP, ci sono casi in cui si
849 preferisce che vengano usate connessioni permanenti con il protocollo TCP. Per
850 ottenere questo\footnote{si potrebbero impostare direttamente le opzioni di
851   \var{\_\_res.options}, ma queste funzioni permettono di semplificare la
852   procedura.} sono previste delle funzioni apposite; la prima è
853 \funcd{sethostent}, il cui prototipo è:
854 \begin{prototype}{netdb.h}
855 {void sethostent(int stayopen)}
856
857 Richiede l'uso di connessioni per le interrogazioni ad un server DNS.
858
859 \bodydesc{La funzione non restituisce nulla.}
860 \end{prototype}
861
862 La funzione permette di richiedere l'uso di connessioni TCP per la richiesta
863 dei dati, e che queste restino aperte per successive richieste. Il valore
864 dell'argomento \param{stayopen} indica se attivare questa funzionalità, un
865 valore pari a 1 (o diverso da zero), che indica una condizione vera in C,
866 attiva la funzionalità.  Come si attiva l'uso delle connessioni TCP lo si può
867 disattivare con la funzione \funcd{endhostent}; il suo prototipo è:
868 \begin{prototype}{netdb.h}
869 {void endhostent(void)}
870
871 Disattiva l'uso di connessioni per le interrogazioni ad un server DNS.
872
873 \bodydesc{La funzione non restituisce nulla.}
874 \end{prototype}
875 \noindent e come si può vedere la funzione è estremamente semplice, non
876 richiedendo nessun argomento.
877
878
879 Infine si può richiedere la risoluzione inversa di un indirizzo IP od IPv6,
880 per ottenerne il nome a dominio ad esso associato, per fare questo si può
881 usare la funzione \funcd{gethostbyaddr}, il cui prototipo è:
882 \begin{functions}
883   \headdecl{netdb.h} 
884   \headdecl{sys/socket.h} 
885   \funcdecl{struct hostent *gethostbyaddr(const char *addr, int len, int type)}
886
887   Richiede la risoluzione inversa di un indirizzo IP.
888        
889   \bodydesc{La funzione restituisce l'indirizzo ad una struttura
890     \struct{hostent} in caso di successo ed \const{NULL} in caso di errore.}
891 \end{functions}
892
893 In questo caso l'argomento \param{addr} dovrà essere il puntatore ad una
894 appropriata struttura contenente il valore dell'indirizzo IP (o IPv6) che si
895 vuole risolvere. L'uso del tipo \texttt{char *} per questo argomento è
896 storico, il dato dovrà essere fornito in una struttura
897 \struct{in\_addr}\footnote{si ricordi che, come illustrato in
898   fig.~\ref{fig:sock_sa_ipv4_struct}, questo in realtà corrisponde ad un
899   numero intero, da esprimere comunque in \textit{network order}, non
900   altrettanto avviene però per \struct{in6\_addr}, pertanto è sempre opportuno
901   inizializzare questi indirizzi con \func{inet\_pton} (vedi
902   sez.~\ref{sec:sock_conv_func_gen}).}  per un indirizzo IPv4 ed una struttura
903 \struct{in6\_addr} per un indirizzo IPv6, mentre in \param{len} se ne dovrà
904 specificare la dimensione (rispettivamente 4 o 16), infine l'argomento
905 \param{type} indica il tipo di indirizzo e dovrà essere o \const{AF\_INET} o
906 \const{AF\_INET6}.
907
908 La funzione restituisce, in caso di successo, un puntatore ad una struttura
909 \struct{hostent}, solo che in questo caso la ricerca viene eseguita
910 richiedendo al DNS un record di tipo \texttt{PTR} corrispondente all'indirizzo
911 specificato. In caso di errore al solito viene usata la variabile
912 \var{h\_errno} per restituire un opportuno codice. In questo caso l'unico
913 campo del risultato che interessa è \var{h\_name} che conterrà il nome a
914 dominio, la funziona comunque inizializza anche il primo campo della lista
915 \var{h\_addr\_list} col valore dell'indirizzo passato come argomento.
916
917 Per risolvere il problema dell'uso da parte delle due funzioni
918 \func{gethostbyname} e \func{gethostbyaddr} di memoria statica che può essere
919 sovrascritta fra due chiamate successive, e per avere sempre la possibilità di
920 indicare esplicitamente il tipo di indirizzi voluto (cosa che non è possibile
921 con \func{gethostbyname}), vennero introdotte due nuove funzioni di
922 risoluzione,\footnote{le funzioni sono presenti nelle \acr{glibc} versione
923   2.1.96, ma essendo considerate deprecate (vedi
924   sez.~\ref{sec:sock_advanced_name_services}) sono state rimosse nelle
925   versioni successive.} \funcd{getipnodebyname} e \funcd{getipnodebyaddr}, i
926 cui prototipi sono:
927 \begin{functions}
928   \headdecl{netdb.h} 
929   \headdecl{sys/types.h} 
930   \headdecl{sys/socket.h} 
931
932   \funcdecl{struct hostent *getipnodebyname(const char *name, int af, int
933     flags, int *error\_num)} 
934
935   \funcdecl{struct hostent *getipnodebyaddr(const void *addr, size\_t len,
936     int af, int *error\_num)}
937
938   Richiedono rispettivamente la risoluzione e la risoluzione inversa di un
939   indirizzo IP.
940        
941   \bodydesc{Entrambe le funzioni restituiscono l'indirizzo ad una struttura
942     \struct{hostent} in caso di successo ed \const{NULL} in caso di errore.}
943 \end{functions}
944
945 Entrambe le funzioni supportano esplicitamente la scelta di una famiglia di
946 indirizzi con l'argomento \param{af} (che può assumere i valori
947 \const{AF\_INET} o \const{AF\_INET6}), e restituiscono un codice di errore
948 (con valori identici a quelli precedentemente illustrati in
949 tab.~\ref{tab:h_errno_values}) nella variabile puntata da \param{error\_num}.
950 La funzione \func{getipnodebyaddr} richiede poi che si specifichi l'indirizzo
951 come per \func{gethostbyaddr} passando anche la lunghezza dello stesso
952 nell'argomento \param{len}.
953
954 La funzione \func{getipnodebyname} prende come primo argomento il nome da
955 risolvere, inoltre prevede un apposito argomento \param{flags}, da usare come
956 maschera binaria, che permette di specificarne il comportamento nella
957 risoluzione dei diversi tipi di indirizzi (IPv4 e IPv6); ciascun bit
958 dell'argomento esprime una diversa opzione, e queste possono essere specificate
959 con un OR aritmetico delle costanti riportate in
960 tab.~\ref{tab:sock_getipnodebyname_flags}.
961
962 \begin{table}[!htb]
963   \centering
964   \footnotesize
965   \begin{tabular}[c]{|l|p{8cm}|}
966     \hline
967     \textbf{Costante} & \textbf{Significato} \\
968     \hline
969     \hline
970     \const{AI\_V4MAPPED}  & Usato con \const{AF\_INET6} per richiedere una
971                             ricerca su un indirizzo IPv4 invece che IPv6; gli
972                             eventuali risultati saranno rimappati su indirizzi 
973                             IPv6.\\
974     \const{AI\_ALL}       & Usato con \const{AI\_V4MAPPED}; richiede sia
975                             indirizzi IPv4 che IPv6, e gli indirizzi IPv4
976                             saranno rimappati in IPv6.\\
977     \const{AI\_ADDRCONFIG}& Richiede che una richiesta IPv4 o IPv6 venga
978                             eseguita solo se almeno una interfaccia del
979                             sistema è associata ad un indirizzo di tale tipo.\\
980     \const{AI\_DEFAULT}   & Il valore di default, è equivalente alla
981                             combinazione di \const{AI\_ADDRCONFIG} e di
982                             \const{AI\_V4MAPPED}.\\  
983     \hline
984   \end{tabular}
985   \caption{Valori possibili per i bit dell'argomento \param{flags} della
986     funzione \func{getipnodebyname}.}
987   \label{tab:sock_getipnodebyname_flags}
988 \end{table}
989
990 Entrambe le funzioni restituiscono un puntatore ad una struttura \var{hostent}
991 che contiene i risultati della ricerca, che viene allocata dinamicamente
992 insieme a tutto lo spazio necessario a contenere i dati in essa referenziati;
993 per questo motivo queste funzioni non soffrono dei problemi dovuti all'uso di
994 una sezione statica di memoria presenti con le precedenti \func{gethostbyname}
995 e \func{gethostbyaddr}.  L'uso di una allocazione dinamica però comporta anche
996 la necessità di disallocare esplicitamente la memoria occupata dai risultati
997 una volta che questi non siano più necessari; a tale scopo viene fornita la
998 funzione \funcd{freehostent}, il cui prototipo è:
999 \begin{functions}
1000   \headdecl{netdb.h} 
1001   \headdecl{sys/types.h} 
1002   \headdecl{sys/socket.h} 
1003
1004   \funcdecl{void freehostent(struct hostent *ip)} 
1005
1006   Disalloca una struttura \var{hostent}.
1007        
1008   \bodydesc{La funzione non ritorna nulla.}
1009 \end{functions}
1010
1011 La funzione permette di disallocare una struttura \var{hostent}
1012 precedentemente allocata in una chiamata di \func{getipnodebyname} o
1013 \func{getipnodebyaddr}, e prende come argomento l'indirizzo restituito da una
1014 di queste funzioni. 
1015
1016 Infine per concludere la nostra panoramica sulle funzioni di risoluzione dei
1017 nomi dobbiamo citare le funzioni che permettono di interrogare gli altri
1018 servizi di risoluzione dei nomi illustrati in sez.~\ref{sec:sock_resolver}; in
1019 generale infatti ci sono una serie di funzioni nella forma
1020 \texttt{getXXXbyname} e \texttt{getXXXbyaddr} (dove \texttt{XXX} indica il
1021 servizio) per ciascuna delle informazioni di rete mantenute dal
1022 \itindex{Name~Service~Switch} \textit{Name Service Switch} che permettono
1023 rispettivamente di trovare una corrispondenza cercando per nome o per numero.
1024
1025 L'elenco di queste funzioni è riportato nelle colonne finali di
1026 tab.~\ref{tab:name_resolution_functions}, dove le si sono suddivise rispetto
1027 al tipo di informazione che forniscono (riportato in prima colonna). Nella
1028 tabella si è anche riportato il file su cui vengono ordinariamente mantenute
1029 queste informazioni, che però può essere sostituito da un qualunque supporto
1030 interno al \itindex{Name~Service~Switch} \textit{Name Service Switch} (anche
1031 se usualmente questo avviene solo per la risoluzione degli indirizzi).
1032 Ciascuna funzione fa riferimento ad una sua apposita struttura che contiene i
1033 relativi dati, riportata in terza colonna.
1034
1035 \begin{table}[!htb]
1036   \centering
1037   \footnotesize
1038   \begin{tabular}[c]{|l|l|l|l|l|}
1039     \hline
1040     \textbf{Informazione}&\textbf{File}&\textbf{Struttura}&
1041     \multicolumn{2}{|c|}{\textbf{Funzioni}}\\
1042     \hline
1043     \hline
1044     indirizzo &\conffile{/etc/hosts}&\struct{hostent}&\func{gethostbyname}&
1045                \func{gethostbyaddr}\\ 
1046     servizio  &\conffile{/etc/services}&\struct{servent}&\func{getservbyname}&
1047                \func{getservbyaddr}\\ 
1048     rete      &\conffile{/etc/networks}&\struct{netent}&\func{getnetbyname}&
1049                \func{getnetbyaddr}\\ 
1050     protocollo&\conffile{/etc/protocols}&\struct{protoent}&
1051                \func{getprotobyname}&\func{getprotobyaddr}\\ 
1052     \hline
1053   \end{tabular}
1054   \caption{Funzioni di risoluzione dei nomi per i vari servizi del
1055     \itindex{Name~Service~Switch} \textit{Name Service Switch}.}
1056   \label{tab:name_resolution_functions}
1057 \end{table}
1058
1059 Delle funzioni di tab.~\ref{tab:name_resolution_functions} abbiamo trattato
1060 finora soltanto quelle relative alla risoluzione dei nomi, dato che sono le
1061 più usate, e prevedono praticamente da sempre la necessità di rivolgersi ad
1062 una entità esterna; per le altre invece, estensioni fornite dal
1063 \itindex{Name~Service~Switch} NSS a parte, si fa sempre riferimento ai dati
1064 mantenuti nei rispettivi file.
1065
1066 Dopo la risoluzione dei nomi a dominio una delle ricerche più comuni è quella
1067 sui nomi dei servizi di rete più comuni (cioè \texttt{http}, \texttt{smtp},
1068 ecc.) da associare alle rispettive porte. Le due funzioni da utilizzare per
1069 questo sono \funcd{getservbyname} e \funcd{getservbyaddr}, che permettono
1070 rispettivamente di ottenere il numero di porta associato ad un servizio dato
1071 il nome e viceversa; i loro prototipi sono:
1072 \begin{functions}
1073   \headdecl{netdb.h} 
1074   \funcdecl{struct servent *getservbyname(const char *name, const char *proto)}
1075   \funcdecl{struct servent *getservbyport(int port, const char *proto)} 
1076
1077   Risolvono il nome di un servizio nel rispettivo numero di porta e viceversa.
1078        
1079   \bodydesc{Ritornano il puntatore ad una struttura \struct{servent} con i
1080     risultati in caso di successo, o \const{NULL} in caso di errore.}
1081 \end{functions}
1082
1083 Entrambe le funzioni prendono come ultimo argomento una stringa \param{proto}
1084 che indica il protocollo per il quale si intende effettuare la
1085 ricerca,\footnote{le informazioni mantenute in \conffile{/etc/services}
1086   infatti sono relative sia alle porte usate su UDP che su TCP, occorre quindi
1087   specificare a quale dei due protocolli si fa riferimento.} che nel caso si
1088 IP può avere come valori possibili solo \texttt{udp} o
1089 \texttt{tcp};\footnote{in teoria si potrebbe avere un qualunque protocollo fra
1090   quelli citati in \conffile{/etc/protocols}, posto che lo stesso supporti il
1091   concetto di \textsl{porta}, in pratica questi due sono gli unici presenti.}
1092 se si specifica un puntatore nullo la ricerca sarà eseguita su un protocollo
1093 qualsiasi.
1094
1095 Il primo argomento è il nome del servizio per \func{getservbyname},
1096 specificato tramite la stringa \param{name}, mentre \func{getservbyport}
1097 richiede il numero di porta in \param{port}. Entrambe le funzioni eseguono una
1098 ricerca sul file \conffile{/etc/services}\footnote{il
1099   \itindex{Name~Service~Switch} \textit{Name Service Switch} astrae il
1100   concetto a qualunque supporto su cui si possano mantenere i suddetti dati.}
1101 ed estraggono i dati dalla prima riga che corrisponde agli argomenti
1102 specificati; se la risoluzione ha successo viene restituito un puntatore ad
1103 una apposita struttura \struct{servent} contenente tutti i risultati,
1104 altrimenti viene restituito un puntatore nullo.  Si tenga presente che anche
1105 in questo caso i dati vengono mantenuti in una area di memoria statica e che
1106 quindi la funzione non è \index{funzioni!rientranti} rientrante.
1107
1108 \begin{figure}[!htb]
1109   \footnotesize \centering
1110   \begin{minipage}[c]{15cm}
1111     \includestruct{listati/servent.h}
1112   \end{minipage}
1113   \caption{La struttura \structd{servent} per la risoluzione dei nomi dei
1114     servizi e dei numeri di porta.}
1115   \label{fig:sock_servent_struct}
1116 \end{figure}
1117
1118 La definizione della struttura \struct{servent} è riportata in
1119 fig.~\ref{fig:sock_servent_struct}, il primo campo, \var{s\_name} contiene
1120 sempre il nome canonico del servizio, mentre \var{s\_aliases} è un puntatore
1121 ad un vettore di stringhe contenenti gli eventuali nomi alternativi
1122 utilizzabili per identificare lo stesso servizio. Infine \var{s\_port}
1123 contiene il numero di porta e \var{s\_proto} il nome del protocollo.
1124
1125 Come riportato in tab.~\ref{tab:name_resolution_functions} ci sono analoghe
1126 funzioni per la risoluzione del nome dei protocolli e delle reti; non staremo
1127 a descriverle nei dettagli, in quanto il loro uso è molto limitato, esse
1128 comunque utilizzano una loro struttura dedicata del tutto analoga alle
1129 precedenti: tutti i dettagli relativi al loro funzionamento possono essere
1130 trovati nelle rispettive pagine di manuale.
1131
1132 Oltre alle funzioni di ricerca esistono delle ulteriori funzioni che prevedono
1133 una lettura sequenziale delle informazioni mantenute nel
1134 \itindex{Name~Service~Switch} \textit{Name Service Switch} (in sostanza
1135 permettono di leggere i file contenenti le informazioni riga per riga), che
1136 sono analoghe a quelle elencate in tab.~\ref{tab:sys_passwd_func} per le
1137 informazioni relative ai dati degli utenti e dei gruppi. Nel caso specifico
1138 dei servizi avremo allora le tre funzioni \funcd{setservent},
1139 \funcd{getservent} e \funcd{endservent} i cui prototipi sono:
1140 \begin{functions}
1141   \headdecl{netdb.h} 
1142   \funcdecl{void setservent(int stayopen)} 
1143   Apre il file \conffile{/etc/services} e si posiziona al suo inizio.
1144
1145   \funcdecl{struct servent *getservent(void)}
1146   Legge la voce successiva nel file \conffile{/etc/services}.      
1147
1148   \funcdecl{void endservent(void)} 
1149   Chiude il file \conffile{/etc/services}.
1150
1151   \bodydesc{Le due funzioni \func{setservent} e \func{endservent} non
1152     restituiscono nulla, \func{getservent} restituisce il puntatore ad una
1153     struttura \struct{servent} in caso di successo e \const{NULL} in caso di
1154     errore o fine del file.}
1155 \end{functions}
1156
1157 La prima funzione, \func{getservent}, legge una singola voce a partire dalla
1158 posizione corrente in \conffile{/etc/services}, pertanto si può eseguire una
1159 lettura sequenziale dello stesso invocandola più volte. Se il file non è
1160 aperto provvede automaticamente ad aprirlo, nel qual caso leggerà la prima
1161 voce. La seconda funzione, \func{setservent}, permette di aprire il file
1162 \conffile{/etc/services} per una successiva lettura, ma se il file è già stato
1163 aperto riporta la posizione di lettura alla prima voce del file, in questo
1164 modo si può far ricominciare da capo una lettura sequenziale. L'argomento
1165 \param{stayopen}, se diverso da zero, fa sì che il file resti aperto anche fra
1166 diverse chiamate a \func{getservbyname} e \func{getservbyaddr}.\footnote{di
1167   default dopo una chiamata a queste funzioni il file viene chiuso, cosicché
1168   una successiva chiamata a \func{getservent} riparte dall'inizio.}  La terza
1169 funzione, \funcd{endservent}, provvede semplicemente a chiudere il file.
1170
1171 Queste tre funzioni per la lettura sequenziale di nuovo sono presenti per
1172 ciascuno dei vari tipi di informazione relative alle reti di
1173 tab.~\ref{tab:name_resolution_functions}; questo significa che esistono
1174 altrettante funzioni nella forma \texttt{setXXXent}, \texttt{getXXXent} e
1175 \texttt{endXXXent}, analoghe alle precedenti per la risoluzione dei servizi,
1176 che abbiamo riportato in tab.~\ref{tab:name_sequential_read}.  Essendo, a
1177 parte il tipo di informazione che viene trattato, sostanzialmente identiche
1178 nel funzionamento e di scarso utilizzo, non staremo a trattarle una per una,
1179 rimandando alle rispettive pagine di manuale.
1180
1181 \begin{table}[!htb]
1182   \centering
1183   \footnotesize
1184   \begin{tabular}[c]{|l|l|l|l|}
1185     \hline
1186     \textbf{Informazione}&\multicolumn{3}{|c|}{\textbf{Funzioni}}\\
1187     \hline
1188     \hline
1189     indirizzo &\func{sethostent} &\func{gethostent} &\func{endhostent} \\
1190     servizio  &\func{setservent} &\func{getservent} &\func{endservent}\\ 
1191     rete      &\func{setnetent}  &\func{getnetent}  &\func{endnetent}\\ 
1192     protocollo&\func{setprotoent}&\func{getprotoent}&\func{endprotoent}\\ 
1193     \hline
1194   \end{tabular}
1195   \caption{Funzioni lettura sequenziale dei dati del
1196     \itindex{Name~Service~Switch} \textit{Name Service Switch}.} 
1197   \label{tab:name_sequential_read}
1198 \end{table}
1199
1200
1201
1202
1203
1204 \subsection{Le funzioni avanzate per la risoluzione dei nomi}
1205 \label{sec:sock_advanced_name_services}
1206
1207 Quelle illustrate nella sezione precedente sono le funzioni classiche per la
1208 risoluzione di nomi ed indirizzi IP, ma abbiamo già visto come esse soffrano
1209 di vari inconvenienti come il fatto che usano informazioni statiche, e non
1210 prevedono la possibilità di avere diverse classi di indirizzi. Anche se sono
1211 state create delle estensioni o metodi diversi che permettono di risolvere
1212 alcuni di questi inconvenienti,\footnote{rimane ad esempio il problema
1213   generico che si deve sapere in anticipo quale tipo di indirizzi IP (IPv4 o
1214   IPv6) corrispondono ad un certo nome a dominio.}  comunque esse non
1215 forniscono una interfaccia sufficientemente generica.
1216
1217 Inoltre in genere quando si ha a che fare con i socket non esiste soltanto il
1218 problema della risoluzione del nome che identifica la macchina, ma anche
1219 quello del servizio a cui ci si vuole rivolgere.  Per questo motivo con lo
1220 standard POSIX 1003.1-2001 sono state indicate come deprecate le varie
1221 funzioni \func{gethostbyaddr}, \func{gethostbyname}, \var{getipnodebyname} e
1222 \var{getipnodebyaddr} ed è stata introdotta una interfaccia completamente
1223 nuova.
1224
1225 La prima funzione di questa interfaccia è \funcd{getaddrinfo},\footnote{la
1226   funzione è definita, insieme a \func{getnameinfo} che vedremo più avanti,
1227   nell'\href{http://www.ietf.org/rfc/rfc2553.txt}{RFC~2553}.} che combina le
1228 funzionalità delle precedenti \func{getipnodebyname}, \func{getipnodebyaddr},
1229 \func{getservbyname} e \func{getservbyport}, consentendo di ottenere
1230 contemporaneamente sia la risoluzione di un indirizzo simbolico che del nome
1231 di un servizio; il suo prototipo è:
1232 \begin{functions}
1233   \headdecl{netdb.h} 
1234   \headdecl{sys/socket.h} 
1235   \headdecl{netdb.h} 
1236
1237   \funcdecl{int getaddrinfo(const char *node, const char *service, const
1238     struct addrinfo *hints, struct addrinfo **res)}
1239
1240   Esegue una risoluzione di un nome a dominio e di un nome di servizio.
1241
1242   \bodydesc{La funzione restituisce 0 in caso di successo o un codice di
1243     errore diverso da zero in caso di fallimento.}
1244 \end{functions}
1245
1246 La funzione prende come primo argomento il nome della macchina che si vuole
1247 risolvere, specificato tramite la stringa \param{node}. Questo argomento,
1248 oltre ad un comune nome a dominio, può indicare anche un indirizzo numerico in
1249 forma \textit{dotted-decimal} per IPv4 o in formato esadecimale per IPv6.  Si
1250 può anche specificare il nome di una rete invece che di una singola macchina.
1251 Il secondo argomento, \param{service}, specifica invece il nome del servizio
1252 che si intende risolvere. Per uno dei due argomenti si può anche usare il
1253 valore \const{NULL}, nel qual caso la risoluzione verrà effettuata soltanto
1254 sulla base del valore dell'altro.
1255
1256 Il terzo argomento, \param{hints}, deve essere invece un puntatore ad una
1257 struttura \struct{addrinfo} usata per dare dei \textsl{suggerimenti} al
1258 procedimento di risoluzione riguardo al protocollo o del tipo di socket che si
1259 intenderà utilizzare; \func{getaddrinfo} infatti permette di effettuare
1260 ricerche generiche sugli indirizzi, usando sia IPv4 che IPv6, e richiedere
1261 risoluzioni sui nomi dei servizi indipendentemente dal protocollo (ad esempio
1262 TCP o UDP) che questi possono utilizzare.
1263
1264 Come ultimo argomento in \param{res} deve essere passato un puntatore ad una
1265 variabile (di tipo puntatore ad una struttura \struct{addrinfo}) che verrà
1266 utilizzata dalla funzione per riportare (come \itindex{value~result~argument}
1267 \textit{value result argument}) i propri risultati. La funzione infatti è
1268 \index{funzioni!rientranti} rientrante, ed alloca autonomamente tutta la
1269 memoria necessaria in cui verranno riportati i risultati della risoluzione.
1270 La funzione scriverà all'indirizzo puntato da \param{res} il puntatore
1271 iniziale ad una \itindex{linked~list} \textit{linked list} di strutture di
1272 tipo \struct{addrinfo} contenenti tutte le informazioni ottenute.
1273
1274 \begin{figure}[!htb]
1275   \footnotesize \centering
1276   \begin{minipage}[c]{15cm}
1277     \includestruct{listati/addrinfo.h}
1278   \end{minipage}
1279   \caption{La struttura \structd{addrinfo} usata nella nuova interfaccia POSIX
1280     per la risoluzione di nomi a dominio e servizi.}
1281   \label{fig:sock_addrinfo_struct}
1282 \end{figure}
1283
1284 Come illustrato la struttura \struct{addrinfo}, la cui definizione\footnote{la
1285   definizione è ripresa direttamente dal file \texttt{netdb.h} in questa
1286   struttura viene dichiarata, la pagina di manuale riporta \type{size\_t} come
1287   tipo di dato per il campo \var{ai\_addrlen}, qui viene usata quanto previsto
1288   dallo standard POSIX, in cui viene utilizzato \type{socklen\_t}; i due tipi
1289   di dati sono comunque equivalenti.} è riportata in
1290 fig.~\ref{fig:sock_addrinfo_struct}, viene usata sia in ingresso, per passare
1291 dei valori di controllo alla funzione, che in uscita, per ricevere i
1292 risultati. Il primo campo, \var{ai\_flags}, è una maschera binaria di bit che
1293 permettono di controllare le varie modalità di risoluzione degli indirizzi,
1294 che viene usato soltanto in ingresso. I tre campi successivi \var{ai\_family},
1295 \var{ai\_socktype}, e \var{ai\_protocol} contengono rispettivamente la
1296 famiglia di indirizzi, il tipo di socket e il protocollo, in ingresso vengono
1297 usati per impostare una selezione (impostandone il valore nella struttura
1298 puntata da \param{hints}), mentre in uscita indicano il tipo di risultato
1299 contenuto nella struttura.
1300
1301 Tutti i campi seguenti vengono usati soltanto in uscita; il campo
1302 \var{ai\_addrlen} indica la dimensione della struttura degli indirizzi
1303 ottenuta come risultato, il cui contenuto sarà memorizzato nella struttura
1304 \struct{sockaddr} posta all'indirizzo puntato dal campo \var{ai\_addr}. Il
1305 campo \var{ai\_canonname} è un puntatore alla stringa contenente il nome
1306 canonico della macchina, ed infine, quando la funzione restituisce più di un
1307 risultato, \var{ai\_next} è un puntatore alla successiva struttura
1308 \struct{addrinfo} della lista.
1309
1310 Ovviamente non è necessario dare dei suggerimenti in ingresso, ed usando
1311 \const{NULL} come valore per l'argomento \param{hints} si possono compiere
1312 ricerche generiche.  Se però si specifica un valore non nullo questo deve
1313 puntare ad una struttura \struct{addrinfo} precedentemente allocata nella
1314 quale siano stati opportunamente impostati i valori dei campi
1315 \var{ai\_family}, \var{ai\_socktype}, \var{ai\_protocol} ed \var{ai\_flags}.
1316
1317 I due campi \var{ai\_family} e \var{ai\_socktype} prendono gli stessi valori
1318 degli analoghi argomenti della funzione \func{socket}; in particolare per
1319 \var{ai\_family} si possono usare i valori di tab.~\ref{tab:net_pf_names} ma
1320 sono presi in considerazione solo \const{PF\_INET} e \const{PF\_INET6}, mentre
1321 se non si vuole specificare nessuna famiglia di indirizzi si può usare il
1322 valore \const{PF\_UNSPEC}.  Allo stesso modo per \var{ai\_socktype} si possono
1323 usare i valori illustrati in sez.~\ref{sec:sock_type} per indicare per quale
1324 tipo di socket si vuole risolvere il servizio indicato, anche se i soli
1325 significativi sono \const{SOCK\_STREAM} e \const{SOCK\_DGRAM}; in questo caso,
1326 se non si vuole effettuare nessuna risoluzione specifica, si potrà usare un
1327 valore nullo.
1328
1329 Il campo \var{ai\_protocol} permette invece di effettuare la selezione dei
1330 risultati per il nome del servizio usando il numero identificativo del
1331 rispettivo protocollo di trasporto (i cui valori possibili sono riportati in
1332 \conffile{/etc/protocols}); di nuovo i due soli valori utilizzabili sono quelli
1333 relativi a UDP e TCP, o il valore nullo che indica di ignorare questo campo
1334 nella selezione.
1335
1336 \begin{table}[!htb]
1337   \centering
1338   \footnotesize
1339   \begin{tabular}[c]{|l|p{10cm}|}
1340     \hline
1341     \textbf{Costante} & \textbf{Significato} \\
1342     \hline
1343     \hline
1344     \const{AI\_PASSIVE}    & Viene utilizzato per ottenere un indirizzo in
1345                              formato adatto per una successiva chiamata a
1346                              \func{bind}. Se specificato quando si è usato 
1347                              \const{NULL} come valore per \param{node} gli
1348                              indirizzi restituiti saranno inizializzati al
1349                              valore generico (\const{INADDR\_ANY} per IPv4 e
1350                              \const{IN6ADDR\_ANY\_INIT} per IPv6), altrimenti
1351                              verrà usato l'indirizzo dell'interfaccia di
1352                              \textit{loopback}. Se invece non è impostato gli
1353                              indirizzi verranno restituiti in formato adatto ad
1354                              una chiamata a \func{connect} o \func{sendto}.\\
1355     \const{AI\_CANONNAME}  & Richiede la restituzione del nome canonico della
1356                              macchina, che verrà salvato in una stringa il cui
1357                              indirizzo sarà restituito nel campo
1358                              \var{ai\_canonname} della prima struttura
1359                              \struct{addrinfo} dei risultati. Se il nome
1360                              canonico non è disponibile al suo posto
1361                              viene restituita una copia di \param{node}. \\ 
1362     \const{AI\_NUMERICHOST}& Se impostato il nome della macchina specificato
1363                              con \param{node} deve essere espresso in forma
1364                              numerica, altrimenti sarà restituito un errore
1365                              \const{EAI\_NONAME} (vedi
1366                              tab.~\ref{tab:addrinfo_error_code}), in questo
1367                              modo si evita ogni chiamata alle funzioni di
1368                              risoluzione.\\ 
1369     \const{AI\_V4MAPPED}   & Stesso significato dell'analoga di
1370                              tab.~\ref{tab:sock_getipnodebyname_flags}.\\  
1371     \const{AI\_ALL}        & Stesso significato dell'analoga di
1372                              tab.~\ref{tab:sock_getipnodebyname_flags}.\\ 
1373     \const{AI\_ADDRCONFIG} & Stesso significato dell'analoga di
1374                              tab.~\ref{tab:sock_getipnodebyname_flags}.\\ 
1375     \hline
1376   \end{tabular}
1377   \caption{Costanti associate ai bit del campo \var{ai\_flags} della struttura 
1378     \struct{addrinfo}.} 
1379   \label{tab:ai_flags_values}
1380 \end{table}
1381
1382
1383 Infine l'ultimo campo è \var{ai\_flags}; che deve essere impostato come una
1384 maschera binaria; i bit di questa variabile infatti vengono usati per dare
1385 delle indicazioni sul tipo di risoluzione voluta, ed hanno valori analoghi a
1386 quelli visti in sez.~\ref{sec:sock_name_services} per \func{getipnodebyname};
1387 il valore di \var{ai\_flags} può essere impostata con un OR aritmetico delle
1388 costanti di tab.~\ref{tab:ai_flags_values}, ciascuna delle quali identifica un
1389 bit della maschera.
1390
1391 La funzione restituisce un valore nullo in caso di successo, o un codice in
1392 caso di errore. I valori usati come codice di errore sono riportati in
1393 tab.~\ref{tab:addrinfo_error_code}; dato che la funzione utilizza altre
1394 funzioni e chiamate al sistema per ottenere il suo risultato in generale il
1395 valore di \var{errno} non è significativo, eccetto il caso in cui si sia
1396 ricevuto un errore di \const{EAI\_SYSTEM}, nel qual caso l'errore
1397 corrispondente è riportato tramite \var{errno}.
1398
1399 \begin{table}[!htb]
1400   \centering
1401   \footnotesize
1402   \begin{tabular}[c]{|l|p{10cm}|}
1403     \hline
1404     \textbf{Costante} & \textbf{Significato} \\
1405     \hline
1406     \hline
1407     \const{EAI\_FAMILY}  & La famiglia di indirizzi richiesta non è
1408                            supportata. \\ 
1409     \const{EAI\_SOCKTYPE}& Il tipo di socket richiesto non è supportato. \\
1410     \const{EAI\_BADFLAGS}& Il campo \var{ai\_flags} contiene dei valori non
1411                            validi. \\
1412     \const{EAI\_NONAME}  & Il nome a dominio o il servizio non sono noti,
1413                            viene usato questo errore anche quando si specifica
1414                            il valore \const{NULL} per entrambi gli argomenti
1415                            \param{node} e \param{service}. \\
1416     \const{EAI\_SERVICE} & Il servizio richiesto non è disponibile per il tipo
1417                            di socket richiesto, anche se può esistere per
1418                            altri tipi di socket. \\
1419     \const{EAI\_ADDRFAMILY}& La rete richiesta non ha nessun indirizzo di rete
1420                            per la famiglia di indirizzi specificata. \\
1421     \const{EAI\_NODATA}  & La macchina specificata esiste, ma non ha nessun
1422                            indirizzo di rete definito. \\
1423     \const{EAI\_MEMORY}  & È stato impossibile allocare la memoria necessaria
1424                            alle operazioni. \\
1425     \const{EAI\_FAIL}    & Il DNS ha restituito un errore di risoluzione  
1426                            permanente. \\
1427     \const{EAI\_AGAIN}   & Il DNS ha restituito un errore di risoluzione  
1428                            temporaneo, si può ritentare in seguito. \\
1429     \const{EAI\_SYSTEM}  & C'è stato un errore di sistema, si può controllare
1430                            \var{errno} per i dettagli. \\
1431 %    \hline
1432 % TODO estensioni GNU, trovarne la documentazione
1433 %    \const{EAI\_INPROGRESS}& Richiesta in corso. \\
1434 %    \const{EAI\_CANCELED}& La richiesta è stata cancellata.\\
1435 %    \const{EAI\_NOTCANCELED}& La richiesta non è stata cancellata. \\
1436 %    \const{EAI\_ALLDONE} & Tutte le richieste sono complete. \\
1437 %    \const{EAI\_INTR}    & Richiesta interrotta. \\
1438     \hline
1439   \end{tabular}
1440   \caption{Costanti associate ai valori dei codici di errore della funzione
1441     \func{getaddrinfo}.} 
1442   \label{tab:addrinfo_error_code}
1443 \end{table}
1444
1445 Come per i codici di errore di \func{gethostbyname} anche in questo caso è
1446 fornita una apposita funzione, analoga di \func{strerror}, che consente di
1447 utilizzarli direttamente per stampare a video un messaggio esplicativo; la
1448 funzione è \func{gai\_strerror} ed il suo prototipo è:
1449 \begin{functions}
1450   \headdecl{netdb.h} 
1451
1452   \funcdecl{const char *gai\_strerror(int errcode)}
1453
1454   Fornisce il messaggio corrispondente ad un errore di \func{getaddrinfo}.
1455
1456   \bodydesc{La funzione restituisce il puntatore alla stringa contenente il
1457     messaggio di errore.}
1458 \end{functions}
1459
1460 La funzione restituisce un puntatore alla stringa contenente il messaggio
1461 corrispondente dal codice di errore \param{errcode} ottenuto come valore di
1462 ritorno di \func{getaddrinfo}.  La stringa è allocata staticamente, ma essendo
1463 costante, ed accessibile in sola lettura, questo non comporta nessun problema
1464 di rientranza della funzione.
1465
1466 Dato che ad un certo nome a dominio possono corrispondere più indirizzi IP
1467 (sia IPv4 che IPv6), e che un certo servizio può essere fornito su protocolli
1468 e tipi di socket diversi, in generale, a meno di non aver eseguito una
1469 selezione specifica attraverso l'uso di \param{hints}, si otterrà una diversa
1470 struttura \struct{addrinfo} per ciascuna possibilità.  Ad esempio se si
1471 richiede la risoluzione del servizio \textit{echo} per l'indirizzo
1472 \texttt{www.truelite.it}, e si imposta \const{AI\_CANONNAME} per avere anche
1473 la risoluzione del nome canonico, si avrà come risposta della funzione la
1474 lista illustrata in fig.~\ref{fig:sock_addrinfo_list}.
1475
1476 \begin{figure}[!htb]
1477   \centering
1478   \includegraphics[width=10cm]{img/addrinfo_list}
1479   \caption{La \itindex{linked~list} \textit{linked list} delle strutture
1480     \struct{addrinfo} restituite da \func{getaddrinfo}.}
1481   \label{fig:sock_addrinfo_list}
1482 \end{figure}
1483
1484 Come primo esempio di uso di \func{getaddrinfo} vediamo un programma
1485 elementare di interrogazione del \itindex{resolver} \textit{resolver} basato
1486 questa funzione, il cui corpo principale è riportato in
1487 fig.~\ref{fig:mygetaddr_example}. Il codice completo del programma, compresa
1488 la gestione delle opzioni in cui è gestita l'eventuale inizializzazione
1489 dell'argomento \var{hints} per restringere le ricerche su protocolli, tipi di
1490 socket o famiglie di indirizzi, è disponibile nel file \texttt{mygetaddr.c}
1491 dei sorgenti allegati alla guida.
1492
1493 \begin{figure}[!htb]
1494   \footnotesize \centering
1495   \begin{minipage}[c]{15cm}
1496     \includecodesample{listati/mygetaddr.c}
1497   \end{minipage}
1498   \normalsize
1499   \caption{Esempio di codice per la risoluzione di un indirizzo.}
1500   \label{fig:mygetaddr_example}
1501 \end{figure}
1502
1503 Il corpo principale inizia controllando (\texttt{\small 1--5}) il numero di
1504 argomenti passati, che devono essere sempre due, e corrispondere
1505 rispettivamente all'indirizzo ed al nome del servizio da risolvere. A questo
1506 segue la chiamata (\texttt{\small 7}) alla funzione \func{getaddrinfo}, ed il
1507 successivo controllo (\texttt{\small 8--11}) del suo corretto funzionamento,
1508 senza il quale si esce immediatamente stampando il relativo codice di errore.
1509
1510 Se la funzione ha restituito un valore nullo il programma prosegue
1511 inizializzando (\texttt{\small 12}) il puntatore \var{ptr} che sarà usato nel
1512 successivo ciclo (\texttt{\small 14--35}) di scansione della lista delle
1513 strutture \struct{addrinfo} restituite dalla funzione. Prima di eseguire
1514 questa scansione (\texttt{\small 12}) viene stampato il valore del nome
1515 canonico che è presente solo nella prima struttura.
1516
1517 La scansione viene ripetuta (\texttt{\small 14}) fintanto che si ha un
1518 puntatore valido. La selezione principale è fatta sul campo \var{ai\_family},
1519 che stabilisce a quale famiglia di indirizzi fa riferimento la struttura in
1520 esame. Le possibilità sono due, un indirizzo IPv4 o IPv6, se nessuna delle due
1521 si verifica si provvede (\texttt{\small 27--30}) a stampare un messaggio di
1522 errore ed uscire.\footnote{questa eventualità non dovrebbe mai verificarsi,
1523   almeno fintanto che la funzione \func{getaddrinfo} lavora correttamente.}
1524
1525 Per ciascuno delle due possibili famiglie di indirizzi si estraggono le
1526 informazioni che poi verranno stampate alla fine del ciclo (\texttt{\small
1527   31--34}). Il primo caso esaminato (\texttt{\small 15--21}) è quello degli
1528 indirizzi IPv4, nel qual caso prima se ne stampa l'identificazione
1529 (\texttt{\small 16}) poi si provvede a ricavare la struttura degli indirizzi
1530 (\texttt{\small 17}) indirizzata dal campo \var{ai\_addr}, eseguendo un
1531 opportuno casting del puntatore per poter estrarre da questa la porta
1532 (\texttt{\small 18}) e poi l'indirizzo (\texttt{\small 19}) che verrà
1533 convertito con una chiamata ad \func{inet\_ntop}.
1534
1535 La stessa operazione (\texttt{\small 21--27}) viene ripetuta per gli indirizzi
1536 IPv6, usando la rispettiva struttura degli indirizzi. Si noti anche come in
1537 entrambi i casi per la chiamata a \func{inet\_ntop} si sia dovuto passare il
1538 puntatore al campo contenente l'indirizzo IP nella struttura puntata dal campo
1539 \var{ai\_addr}.\footnote{il meccanismo è complesso a causa del fatto che al
1540   contrario di IPv4, in cui l'indirizzo IP può essere espresso con un semplice
1541   numero intero, in IPv6 questo deve essere necessariamente fornito come
1542   struttura, e pertanto anche se nella struttura puntata da \var{ai\_addr}
1543   sono presenti direttamente i valori finali, per l'uso con \func{inet\_ntop}
1544   occorre comunque passare un puntatore agli stessi (ed il costrutto
1545   \code{\&addr6->sin6\_addr} è corretto in quanto l'operatore \texttt{->} ha
1546   on questo caso precedenza su \texttt{\&}).}
1547
1548 Una volta estratte dalla struttura \struct{addrinfo} tutte le informazioni
1549 relative alla risoluzione richiesta e stampati i relativi valori, l'ultimo
1550 passo (\texttt{\small 34}) è di estrarre da \var{ai\_next} l'indirizzo della
1551 eventuale successiva struttura presente nella lista e ripetere il ciclo, fin
1552 tanto che, completata la scansione, questo avrà un valore nullo e si potrà
1553 terminare (\texttt{\small 36}) il programma.
1554
1555 Si tenga presente che \func{getaddrinfo} non garantisce nessun particolare
1556 ordinamento della lista delle strutture \struct{addrinfo} restituite, anche se
1557 usualmente i vari indirizzi IP (se ne è presente più di uno) sono forniti
1558 nello stesso ordine in cui vengono inviati dal server DNS. In particolare
1559 nulla garantisce che vengano forniti prima i dati relativi ai servizi di un
1560 determinato protocollo o tipo di socket, se ne sono presenti di diversi.  Se
1561 allora utilizziamo il nostro programma potremo verificare il risultato:
1562 \begin{Verbatim}
1563 [piccardi@gont sources]$ ./mygetaddr -c  gapil.truelite.it echo
1564 Canonical name sources2.truelite.it
1565 IPv4 address:
1566         Indirizzo 62.48.34.25
1567         Protocollo 6
1568         Porta 7
1569 IPv4 address:
1570         Indirizzo 62.48.34.25
1571         Protocollo 17
1572         Porta 7
1573 \end{Verbatim}
1574 %$
1575
1576 Una volta estratti i risultati dalla \itindex{linked~list} \textit{linked list}
1577 puntata da \param{res} se questa non viene più utilizzata si dovrà avere cura
1578 di disallocare opportunamente tutta la memoria, per questo viene fornita
1579 l'apposita funzione \funcd{freeaddrinfo}, il cui prototipo è:
1580 \begin{functions}
1581   \headdecl{netdb.h} 
1582
1583   \funcdecl{void freeaddrinfo(struct addrinfo *res)}
1584
1585   Libera la memoria allocata da una precedente chiamata a \func{getaddrinfo}.
1586
1587   \bodydesc{La funzione non restituisce nessun codice di errore.}
1588 \end{functions}
1589
1590 La funzione prende come unico argomento il puntatore \param{res}, ottenuto da
1591 una precedente chiamata a \func{getaddrinfo}, e scandisce la lista delle
1592 strutture per liberare tutta la memoria allocata. Dato che la funzione non ha
1593 valori di ritorno deve essere posta molta cura nel passare un valore valido
1594 per \param{res}.
1595
1596 Si tenga presente infine che se si copiano i risultati da una delle strutture
1597 \struct{addrinfo} restituite nella lista indicizzata da \param{res}, occorre
1598 avere cura di eseguire una \itindex{deep~copy} \textit{deep copy} in cui
1599 si copiano anche tutti i dati presenti agli indirizzi contenuti nella
1600 struttura \struct{addrinfo}, perché una volta disallocati i dati con
1601 \func{freeaddrinfo} questi non sarebbero più disponibili. 
1602
1603 Anche la nuova interfaccia definita da POSIX prevede una nuova funzione per
1604 eseguire la risoluzione inversa e determinare nomi di servizi e di dominio
1605 dati i rispettivi valori numerici. La funzione che sostituisce le varie
1606 \func{gethostbyname}, \func{getipnodebyname} e \func{getservname} è
1607 \funcd{getnameinfo}, ed il suo prototipo è:
1608 \begin{functions}
1609   \headdecl{sys/socket.h}
1610   \headdecl{netdb.h}
1611
1612   \funcdecl{int getnameinfo(const struct sockaddr *sa, socklen\_t salen, char
1613     *host, size\_t hostlen, char *serv, size\_t servlen, int flags)}
1614
1615   Risolve il contenuto di una struttura degli indirizzi in maniera
1616   indipendente dal protocollo.
1617
1618   \bodydesc{La funzione restituisce 0 in caso di successo e un codice di
1619     errore diverso da zero altrimenti.}
1620 \end{functions}
1621
1622 La principale caratteristica di \func{getnameinfo} è che la funzione è in
1623 grado di eseguire una risoluzione inversa in maniera indipendente dal
1624 protocollo; il suo primo argomento \param{sa} infatti è il puntatore ad una
1625 struttura degli indirizzi generica, che può contenere sia indirizzi IPv4 che
1626 IPv6, la cui dimensione deve comunque essere specificata con l'argomento
1627 \param{salen}. 
1628
1629 I risultati della funzione saranno restituiti nelle due stringhe puntate da
1630 \param{host} e \param{serv}, che dovranno essere state precedentemente
1631 allocate per una lunghezza massima che deve essere specificata con gli altri
1632 due argomenti \param{hostlen} e \param{servlen}. Si può, quando non si è
1633 interessati ad uno dei due, passare il valore \const{NULL} come argomento,
1634 così che la corrispondente informazione non verrà richiesta. Infine l'ultimo
1635 argomento \param{flags} è una maschera binaria i cui bit consentono di
1636 impostare le modalità con cui viene eseguita la ricerca, e deve essere
1637 specificato attraverso l'OR aritmetico dei valori illustrati in
1638 tab.~\ref{tab:getnameinfo_flags}.
1639
1640 \begin{table}[!htb]
1641   \centering
1642   \footnotesize
1643   \begin{tabular}[c]{|l|p{10cm}|}
1644     \hline
1645     \textbf{Costante} & \textbf{Significato} \\
1646     \hline
1647     \hline
1648     \const{NI\_NOFQDN}     & Richiede che venga restituita solo il nome della
1649                              macchina all'interno del dominio al posto del
1650                              nome completo (FQDN).\\
1651     \const{NI\_NUMERICHOST}& Richiede che venga restituita la forma numerica
1652                              dell'indirizzo (questo succede sempre se il nome
1653                              non può essere ottenuto).\\ 
1654     \const{NI\_NAMEREQD}   & Richiede la restituzione di un errore se il nome
1655                              non può essere risolto.\\
1656     \const{NI\_NUMERICSERV}& Richiede che il servizio venga restituito in
1657                              forma numerica (attraverso il numero di porta).\\
1658     \const{NI\_DGRAM}      & Richiede che venga restituito il nome del
1659                              servizio su UDP invece che quello su TCP per quei
1660                              pichi servizi (porte 512-214) che soni diversi
1661                              nei due protocolli.\\
1662     \hline
1663   \end{tabular}
1664   \caption{Costanti associate ai bit dell'argomento \param{flags} della  
1665     funzione \func{getnameinfo}.} 
1666   \label{tab:getnameinfo_flags}
1667 \end{table}
1668
1669 La funzione ritorna zero in caso di successo, e scrive i propri risultati agli
1670 indirizzi indicati dagli argomenti \param{host} e \param{serv} come stringhe
1671 terminate dal carattere NUL, a meno che queste non debbano essere troncate
1672 qualora la loro dimensione ecceda quelle specificate dagli argomenti
1673 \param{hostlen} e \param{servlen}. Sono comunque definite le due costanti
1674 \const{NI\_MAXHOST} e \const{NI\_MAXSERV}\footnote{in Linux le due costanti
1675   sono definite in \file{netdb.h} ed hanno rispettivamente il valore 1024 e
1676   12.}  che possono essere utilizzate come limiti massimi.  In caso di errore
1677 viene restituito invece un codice che assume gli stessi valori illustrati in
1678 tab.~\ref{tab:addrinfo_error_code}.
1679
1680 A questo punto possiamo fornire degli esempi di utilizzo della nuova
1681 interfaccia, adottandola per le precedenti implementazioni del client e del
1682 server per il servizio \textit{echo}; dato che l'uso delle funzioni appena
1683 illustrate (in particolare di \func{getaddrinfo}) è piuttosto complesso,
1684 essendo necessaria anche una impostazione diretta dei campi dell'argomento
1685 \param{hints}, provvederemo una interfaccia semplificata per i due casi visti
1686 finora, quello in cui si specifica nel client un indirizzo remoto per la
1687 connessione al server, e quello in cui si specifica nel server un indirizzo
1688 locale su cui porsi in ascolto.
1689
1690 La prima funzione della nostra interfaccia semplificata è \func{sockconn} che
1691 permette di ottenere un socket, connesso all'indirizzo ed al servizio
1692 specificati. Il corpo della funzione è riportato in
1693 fig.~\ref{fig:sockconn_code}, il codice completo è nel file \file{SockUtil.c}
1694 dei sorgenti allegati alla guida, che contiene varie funzioni di utilità per
1695 l'uso dei socket.
1696
1697 \begin{figure}[!htb]
1698   \footnotesize \centering
1699   \begin{minipage}[c]{15cm}
1700     \includecodesample{listati/sockconn.c}
1701   \end{minipage}
1702   \normalsize
1703   \caption{Il codice della funzione \func{sockconn}.}
1704   \label{fig:sockconn_code}
1705 \end{figure}
1706
1707 La funzione prende quattro argomenti, i primi due sono le stringhe che
1708 indicano il nome della macchina a cui collegarsi ed il relativo servizio su
1709 cui sarà effettuata la risoluzione; seguono il protocollo da usare (da
1710 specificare con il valore numerico di \conffile{/etc/protocols}) ed il tipo di
1711 socket (al solito specificato con i valori illustrati in
1712 sez.~\ref{sec:sock_type}).  La funzione ritorna il valore del file descriptor
1713 associato al socket (un numero positivo) in caso di successo, o -1 in caso di
1714 errore; per risolvere il problema di non poter passare indietro i valori di
1715 ritorno di \func{getaddrinfo} contenenti i relativi codici di
1716 errore\footnote{non si può avere nessuna certezza che detti valori siano
1717   negativi, è questo è invece necessario per evitare ogni possibile ambiguità
1718   nei confronti del valore di ritorno in caso di successo.} si sono stampati i
1719 messaggi d'errore direttamente nella funzione.
1720
1721 Una volta definite le variabili necessarie (\texttt{\small 3--5}) la funzione
1722 prima (\texttt{\small 6}) azzera il contenuto della struttura \var{hint} e poi
1723 provvede (\texttt{\small 7--9}) ad inizializzarne i valori necessari per la
1724 chiamata (\texttt{\small 10}) a \func{getaddrinfo}. Di quest'ultima si
1725 controlla (\texttt{\small 12-16}) il codice di ritorno, in modo da stampare un
1726 avviso di errore, azzerare \var{errno} ed uscire in caso di errore.  Dato che
1727 ad una macchina possono corrispondere più indirizzi IP, e di tipo diverso (sia
1728 IPv4 che IPv6), mentre il servizio può essere in ascolto soltanto su uno solo
1729 di questi, si provvede a tentare la connessione per ciascun indirizzo
1730 restituito all'interno di un ciclo (\texttt{\small 18-40}) di scansione della
1731 lista restituita da \func{getaddrinfo}, ma prima (\texttt{\small 17}) si salva
1732 il valore del puntatore per poterlo riutilizzare alla fine per disallocare la
1733 lista.
1734
1735 Il ciclo viene ripetuto (\texttt{\small 18}) fintanto che si hanno indirizzi
1736 validi, ed inizia (\texttt{\small 19}) con l'apertura del socket; se questa
1737 fallisce si controlla (\texttt{\small 20}) se sono disponibili altri
1738 indirizzi, nel qual caso si passa al successivo (\texttt{\small 21}) e si
1739 riprende (\texttt{\small 22}) il ciclo da capo; se non ve ne sono si stampa
1740 l'errore ritornando immediatamente (\texttt{\small 24-27}). Quando la
1741 creazione del socket ha avuto successo si procede (\texttt{\small 29})
1742 direttamente con la connessione, di nuovo in caso di fallimento viene ripetuto
1743 (\texttt{\small 30--38}) il controllo se vi sono o no altri indirizzi da
1744 provare nella stessa modalità fatta in precedenza, aggiungendovi però in
1745 entrambi i casi (\texttt{\small 32} e (\texttt{\small 36}) la chiusura del
1746 socket precedentemente aperto, che non è più utilizzabile.
1747
1748 Se la connessione ha avuto successo invece si termina (\texttt{\small 39})
1749 direttamente il ciclo, e prima di ritornare (\texttt{\small 31}) il valore del
1750 file descriptor del socket si provvede (\texttt{\small 30}) a liberare le
1751 strutture \struct{addrinfo} allocate da \func{getaddrinfo} utilizzando il
1752 valore del relativo puntatore precedentemente (\texttt{\small 17}) salvato.
1753 Si noti come per la funzione sia del tutto irrilevante se la struttura
1754 ritornata contiene indirizzi IPv6 o IPv4, in quanto si fa uso direttamente dei
1755 dati relativi alle strutture degli indirizzi di \struct{addrinfo} che sono
1756 \textsl{opachi} rispetto all'uso della funzione \func{connect}.
1757
1758 \begin{figure}[!htb]
1759   \footnotesize \centering
1760   \begin{minipage}[c]{15cm}
1761     \includecodesample{listati/TCP_echo_fifth.c}
1762   \end{minipage}
1763   \normalsize
1764   \caption{Il nuovo codice per la connessione del client \textit{echo}.}
1765   \label{fig:TCP_echo_fifth}
1766 \end{figure}
1767
1768 Per usare questa funzione possiamo allora modificare ulteriormente il nostro
1769 programma client per il servizio \textit{echo}; in questo caso rispetto al
1770 codice usato finora per collegarsi (vedi fig.~\ref{fig:TCP_echo_client_1})
1771 avremo una semplificazione per cui il corpo principale del nostro client
1772 diventerà quello illustrato in fig.~\ref{fig:TCP_echo_fifth}, in cui le
1773 chiamate a \func{socket}, \func{inet\_pton} e \func{connect} sono sostituite
1774 da una singola chiamata a \func{sockconn}. Inoltre il nuovo client (il cui
1775 codice completo è nel file \file{TCP\_echo\_fifth.c} dei sorgenti allegati)
1776 consente di utilizzare come argomento del programma un nome a dominio al posto
1777 dell'indirizzo numerico, e può utilizzare sia indirizzi IPv4 che IPv6.
1778
1779 \begin{figure}[!htb]
1780   \footnotesize \centering
1781   \begin{minipage}[c]{15cm}
1782     \includecodesample{listati/sockbind.c}
1783   \end{minipage}
1784   \normalsize
1785   \caption{Il codice della funzione \func{sockbind}.}
1786   \label{fig:sockbind_code}
1787 \end{figure}
1788
1789 La seconda funzione di ausilio è \func{sockbind}, il cui corpo principale è
1790 riportato in fig.~\ref{fig:sockbind_code} (al solito il sorgente completo è
1791 nel file \file{sockbind.c} dei sorgenti allegati alla guida). Come si può
1792 notare la funzione è del tutto analoga alla precedente \func{sockconn}, e
1793 prende gli stessi argomenti, però invece di eseguire una connessione con
1794 \func{connect} si limita a chiamare \func{bind} per collegare il socket ad una
1795 porta.
1796
1797 Dato che la funzione è pensata per essere utilizzata da un server ci si può
1798 chiedere a quale scopo mantenere l'argomento \param{host} quando l'indirizzo
1799 di questo è usualmente noto. Si ricordi però quanto detto in
1800 sez.~\ref{sec:TCP_func_bind}, relativamente al significato della scelta di un
1801 indirizzo specifico come argomento di \func{bind}, che consente di porre il
1802 server in ascolto su uno solo dei possibili diversi indirizzi presenti su di
1803 una macchina.  Se non si vuole che la funzione esegua \func{bind} su un
1804 indirizzo specifico, ma utilizzi l'indirizzo generico, occorrerà avere cura di
1805 passare un valore \const{NULL} come valore per l'argomento \var{host}; l'uso
1806 del valore \const{AI\_PASSIVE} serve ad ottenere il valore generico nella
1807 rispettiva struttura degli indirizzi.
1808
1809 Come già detto la funzione è analoga a \func{sockconn} ed inizia azzerando ed
1810 inizializzando (\texttt{\small 6-11}) opportunamente la struttura \var{hint}
1811 con i valori ricevuti come argomenti, soltanto che in questo caso si è usata
1812 (\texttt{\small 8}) una impostazione specifica dei flag di \var{hint} usando
1813 \const{AI\_PASSIVE} per indicare che il socket sarà usato per una apertura
1814 passiva. Per il resto la chiamata (\texttt{\small 12-18}) a \func{getaddrinfo}
1815 e ed il ciclo principale (\texttt{\small 20--42}) sono identici, solo che si è
1816 sostituita (\texttt{\small 31}) la chiamata a \func{connect} con una chiamata
1817 a \func{bind}. Anche la conclusione (\texttt{\small 43--44}) della funzione è
1818 identica. 
1819
1820 Si noti come anche in questo caso si siano inserite le stampe degli errori
1821 sullo standard error, nonostante la funzione possa essere invocata da un
1822 demone. Nel nostro caso questo non è un problema in quanto se la funzione non
1823 ha successo il programma deve uscire immediatamente prima di essere posto in
1824 background, e può quindi scrivere gli errori direttamente sullo standard
1825 error.
1826
1827 \begin{figure}[!htb]
1828   \footnotesize \centering
1829   \begin{minipage}[c]{15cm}
1830     \includecodesample{listati/TCP_echod_third.c}
1831   \end{minipage}
1832   \normalsize
1833   \caption{Nuovo codice per l'apertura passiva del server \textit{echo}.}
1834   \label{fig:TCP_echod_third}
1835 \end{figure}
1836
1837 Con l'uso di questa funzione si può modificare anche il codice del nostro
1838 server \textit{echo}, che rispetto a quanto illustrato nella versione iniziale
1839 di fig.~\ref{fig:TCP_echo_server_first_code} viene modificato nella forma
1840 riportata in fig.~\ref{fig:TCP_echod_third}. In questo caso il socket su cui
1841 porsi in ascolto viene ottenuto (\texttt{\small 15--18}) da \func{sockbind}
1842 che si cura anche della eventuale risoluzione di un indirizzo specifico sul
1843 quale si voglia far ascoltare il server.
1844
1845
1846
1847 \section{Le opzioni dei socket}
1848 \label{sec:sock_options}
1849
1850 Benché dal punto di vista del loro uso come canali di trasmissione di dati i
1851 socket siano trattati allo stesso modo dei file, ed acceduti tramite i file
1852 descriptor, la normale interfaccia usata per la gestione dei file non è
1853 sufficiente a poterne controllare tutte le caratteristiche, che variano tra
1854 l'altro a seconda del loro tipo (e della relativa forma di comunicazione
1855 sottostante). In questa sezione vedremo allora quali sono le funzioni dedicate
1856 alla gestione delle caratteristiche specifiche dei vari tipi di socket, le
1857 cosiddette \textit{socket options}.
1858
1859
1860 \subsection{Le funzioni \func{setsockopt} e \func{getsockopt}}
1861 \label{sec:sock_setsockopt}
1862
1863 Le varie caratteristiche dei socket possono essere gestite attraverso l'uso di
1864 due funzioni generiche che permettono rispettivamente di impostarle e di
1865 recuperarne il valore corrente. La prima di queste due funzioni, quella usata
1866 per impostare le \textit{socket options}, è \funcd{setsockopt}, ed il suo
1867 prototipo è:
1868 \begin{functions}
1869   \headdecl{sys/socket.h}
1870   \headdecl{sys/types.h}
1871
1872   \funcdecl{int setsockopt(int sock, int level, int optname, const void
1873     *optval, socklen\_t optlen)}
1874   Imposta le opzioni di un socket.
1875
1876   \bodydesc{La funzione restituisce 0 in caso di successo e -1 in caso di
1877     errore, nel qual caso \var{errno} assumerà i valori:
1878   \begin{errlist}
1879   \item[\errcode{EBADF}]  il file descriptor \param{sock} non è valido.
1880   \item[\errcode{EFAULT}] l'indirizzo \param{optval} non è valido.
1881   \item[\errcode{EINVAL}] il valore di \param{optlen} non è valido.
1882   \item[\errcode{ENOPROTOOPT}] l'opzione scelta non esiste per il livello
1883     indicato. 
1884   \item[\errcode{ENOTSOCK}] il file descriptor \param{sock} non corrisponde ad
1885     un socket.
1886   \end{errlist}
1887 }
1888 \end{functions}
1889
1890
1891 Il primo argomento della funzione, \param{sock}, indica il socket su cui si
1892 intende operare; per indicare l'opzione da impostare si devono usare i due
1893 argomenti successivi, \param{level} e \param{optname}.  Come abbiamo visto in
1894 sez.~\ref{sec:net_protocols} i protocolli di rete sono strutturati su vari
1895 livelli, ed l'interfaccia dei socket può usarne più di uno. Si avranno allora
1896 funzionalità e caratteristiche diverse per ciascun protocollo usato da un
1897 socket, e quindi saranno anche diverse le opzioni che si potranno impostare
1898 per ciascun socket, a seconda del \textsl{livello} (trasporto, rete, ecc.) su
1899 cui si vuole andare ad operare.
1900
1901 Il valore di \param{level} seleziona allora il protocollo su cui vuole
1902 intervenire, mentre \param{optname} permette di scegliere su quale delle
1903 opzioni che sono definite per quel protocollo si vuole operare. In sostanza la
1904 selezione di una specifica opzione viene fatta attraverso una coppia di valori
1905 \param{level} e \param{optname} e chiaramente la funzione avrà successo
1906 soltanto se il protocollo in questione prevede quella opzione ed è utilizzato
1907 dal socket.  Infine \param{level} prevede anche il valore speciale
1908 \const{SOL\_SOCKET} usato per le opzioni generiche che sono disponibili per
1909 qualunque tipo di socket.
1910
1911 I valori usati per \param{level}, corrispondenti ad un dato protocollo usato
1912 da un socket, sono quelli corrispondenti al valore numerico che identifica il
1913 suddetto protocollo in \conffile{/etc/protocols}; dato che la leggibilità di un
1914 programma non trarrebbe certo beneficio dall'uso diretto dei valori numerici,
1915 più comunemente si indica il protocollo tramite le apposite costanti
1916 \texttt{SOL\_*} riportate in tab.~\ref{tab:sock_option_levels}, dove si sono
1917 riassunti i valori che possono essere usati per l'argomento
1918 \param{level}.\footnote{la notazione in questo caso è, purtroppo, abbastanza
1919   confusa: infatti in Linux il valore si può impostare sia usando le costanti
1920   \texttt{SOL\_*}, che le analoghe \texttt{IPPROTO\_*} (citate anche da
1921   Stevens in \cite{UNP1}); entrambe hanno gli stessi valori che sono
1922   equivalenti ai numeri di protocollo di \conffile{/etc/protocols}, con una
1923   eccezione specifica, che è quella del protocollo ICMP, per la quale non
1924   esista una costante, il che è comprensibile dato che il suo valore, 1, è
1925   quello che viene assegnato a \const{SOL\_SOCKET}.}
1926
1927 \begin{table}[!htb]
1928   \centering
1929   \footnotesize
1930   \begin{tabular}[c]{|l|l|}
1931     \hline
1932     \textbf{Livello} & \textbf{Significato} \\
1933     \hline
1934     \hline
1935     \const{SOL\_SOCKET}& Opzioni generiche dei socket.\\
1936     \const{SOL\_IP}    & Opzioni specifiche per i socket che usano IPv4.\\
1937     \const{SOL\_TCP}   & Opzioni per i socket che usano TCP.\\
1938     \const{SOL\_IPV6}  & Opzioni specifiche per i socket che usano IPv6.\\
1939     \const{SOL\_ICMPV6}& Opzioni specifiche per i socket che usano ICMPv6.\\
1940     \hline
1941   \end{tabular}
1942   \caption{Possibili valori dell'argomento \param{level} delle 
1943     funzioni \func{setsockopt} e \func{getsockopt}.} 
1944   \label{tab:sock_option_levels}
1945 \end{table}
1946
1947 Il quarto argomento, \param{optval} è un puntatore ad una zona di memoria che
1948 contiene i dati che specificano il valore dell'opzione che si vuole passare al
1949 socket, mentre l'ultimo argomento \param{optlen},\footnote{questo argomento è
1950   in realtà sempre di tipo \ctyp{int}, come era nelle \acr{libc4} e
1951   \acr{libc5}; l'uso di \ctyp{socklen\_t} è stato introdotto da POSIX (valgono
1952   le stesse considerazioni per l'uso di questo tipo di dato fatte in
1953   sez.~\ref{sec:TCP_func_accept}) ed adottato dalle \acr{glibc}.} è la
1954 dimensione in byte dei dati presenti all'indirizzo indicato da \param{optval}.
1955 Dato che il tipo di dati varia a seconda dell'opzione scelta, occorrerà
1956 individuare qual è quello che deve essere usato, ed utilizzare le opportune
1957 variabili.
1958
1959 La gran parte delle opzioni utilizzano per \param{optval} un valore intero, se
1960 poi l'opzione esprime una condizione logica, il valore è sempre un intero, ma
1961 si dovrà usare un valore non nullo per abilitarla ed un valore nullo per
1962 disabilitarla.  Se invece l'opzione non prevede di dover ricevere nessun tipo
1963 di valore si deve impostare \param{optval} a \const{NULL}. Un piccolo numero
1964 di opzioni però usano dei tipi di dati peculiari, è questo il motivo per cui
1965 \param{optval} è stato definito come puntatore generico.
1966
1967 La seconda funzione usata per controllare le proprietà dei socket è
1968 \funcd{getsockopt}, che serve a leggere i valori delle opzioni dei socket ed a
1969 farsi restituire i dati relativi al loro funzionamento; il suo prototipo è:
1970 \begin{functions}
1971   \headdecl{sys/socket.h}
1972   \headdecl{sys/types.h}
1973
1974   \funcdecl{int getsockopt(int s, int level, int optname, void *optval,
1975     socklen\_t *optlen)} Legge le opzioni di un socket.
1976
1977   \bodydesc{La funzione restituisce 0 in caso di successo e -1 in caso di
1978     errore, nel qual caso \var{errno} assumerà i valori:
1979   \begin{errlist}
1980   \item[\errcode{EBADF}] il file descriptor \param{sock} non è valido.
1981   \item[\errcode{EFAULT}] l'indirizzo \param{optval} o quello di
1982     \param{optlen} non è valido.
1983   \item[\errcode{ENOPROTOOPT}] l'opzione scelta non esiste per il livello
1984     indicato. 
1985   \item[\errcode{ENOTSOCK}] il file descriptor \param{sock} non corrisponde ad
1986     un socket.
1987   \end{errlist}
1988 }
1989 \end{functions}
1990
1991 I primi tre argomenti sono identici ed hanno lo stesso significato di quelli
1992 di \func{setsockopt}, anche se non è detto che tutte le opzioni siano definite
1993 per entrambe le funzioni. In questo caso \param{optval} viene usato per
1994 ricevere le informazioni ed indica l'indirizzo a cui andranno scritti i dati
1995 letti dal socket, infine \param{optlen} diventa un puntatore ad una variabile
1996 che viene usata come \itindex{value~result~argument} \textit{value result
1997   argument} per indicare, prima della chiamata della funzione, la lunghezza
1998 del buffer allocato per \param{optval} e per ricevere indietro, dopo la
1999 chiamata della funzione, la dimensione effettiva dei dati scritti su di esso.
2000 Se la dimensione del buffer allocato per \param{optval} non è sufficiente si
2001 avrà un errore.
2002
2003
2004
2005 \subsection{Le opzioni generiche}
2006 \label{sec:sock_generic_options}
2007
2008 Come accennato esiste un insieme generico di opzioni dei socket che possono
2009 applicarsi a qualunque tipo di socket,\footnote{una descrizione di queste
2010   opzioni è generalmente disponibile nella settima sezione delle pagine di
2011   manuale, nel caso specifico la si può consultare con \texttt{man 7 socket}.}
2012 indipendentemente da quale protocollo venga poi utilizzato. Se si vuole
2013 operare su queste opzioni generiche il livello da utilizzare è
2014 \const{SOL\_SOCKET}; si è riportato un elenco di queste opzioni in
2015 tab.~\ref{tab:sock_opt_socklevel}.
2016
2017
2018 \begin{table}[!htb]
2019   \centering
2020   \footnotesize
2021   \begin{tabular}[c]{|l|c|c|c|l|l|}
2022     \hline
2023     \textbf{Opzione}&\texttt{get}&\texttt{set}&\textbf{flag}&\textbf{Tipo}&
2024                     \textbf{Descrizione}\\
2025     \hline
2026     \hline
2027     \const{SO\_KEEPALIVE}&$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2028                           Controlla l'attività della connessione.\\
2029     \const{SO\_OOBINLINE}&$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2030                           Lascia in linea i dati \itindex{out-of-band}
2031                           \textit{out-of-band}.\\
2032     \const{SO\_RCVLOWAT} &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2033                           Basso livello sul buffer di ricezione.\\
2034     \const{SO\_SNDLOWAT} &$\bullet$&$\bullet$&         &\texttt{int}&
2035                           Basso livello sul buffer di trasmissione.\\
2036     \const{SO\_RCVTIMEO} &$\bullet$&$\bullet$&         &\texttt{timeval}& 
2037                           Timeout in ricezione.\\
2038     \const{SO\_SNDTIMEO} &$\bullet$&$\bullet$&         &\texttt{timeval}& 
2039                           Timeout in trasmissione.\\
2040     \const{SO\_BSDCOMPAT}&$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2041                           Abilita la compatibilità con BSD.\\
2042     \const{SO\_PASSCRED} &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2043                           Abilita la ricezione di credenziali.\\
2044     \const{SO\_PEERCRED} &$\bullet$&         &         &\texttt{ucred}& 
2045                           Restituisce le credenziali del processo remoto.\\
2046     \const{SO\_BINDTODEVICE}&$\bullet$&$\bullet$&         &\texttt{char *}& 
2047                           Lega il socket ad un dispositivo.\\
2048     \const{SO\_DEBUG}    &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2049                           Abilita il debugging sul socket.\\
2050     \const{SO\_REUSEADDR}&$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2051                           Consente il riutilizzo di un indirizzo locale.\\
2052     \const{SO\_TYPE}     &$\bullet$&         &         &\texttt{int}& 
2053                           Restituisce il tipo di socket.\\
2054     \const{SO\_ACCEPTCONN}&$\bullet$&        &         &\texttt{int}& 
2055                           Indica se il socket è in ascolto.\\
2056     \const{SO\_DONTROUTE}&$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2057                           Non invia attraverso un gateway.\\
2058     \const{SO\_BROADCAST}&$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2059                           Attiva o disattiva il \itindex{broadcast}
2060                           \textit{broadcast}.\\ 
2061     \const{SO\_SNDBUF}   &$\bullet$&$\bullet$&         &\texttt{int}& 
2062                           Imposta dimensione del buffer di trasmissione.\\
2063     \const{SO\_RCVBUF}   &$\bullet$&$\bullet$&         &\texttt{int}& 
2064                           Imposta dimensione del buffer di ricezione.\\
2065     \const{SO\_LINGER}   &$\bullet$&$\bullet$&         &\texttt{linger}&
2066                           Indugia nella chiusura con dati da spedire.\\
2067     \const{SO\_PRIORITY} &$\bullet$&$\bullet$&         &\texttt{int}& 
2068                           Imposta la priorità del socket.\\
2069     \const{SO\_ERROR}    &$\bullet$&         &         &\texttt{int}& 
2070                           Riceve e cancella gli errori pendenti.\\
2071    \hline
2072   \end{tabular}
2073   \caption{Le opzioni disponibili al livello \const{SOL\_SOCKET}.} 
2074   \label{tab:sock_opt_socklevel}
2075 \end{table}
2076
2077 La tabella elenca le costanti che identificano le singole opzioni da usare
2078 come valore per \param{optname}; le due colonne seguenti indicano per quali
2079 delle due funzioni (\func{getsockopt} o \func{setsockopt}) l'opzione è
2080 disponibile, mentre la colonna successiva indica, quando di ha a che fare con
2081 un valore di \param{optval} intero, se l'opzione è da considerare un numero o
2082 un valore logico. Si è inoltre riportato sulla quinta colonna il tipo di dato
2083 usato per \param{optval} ed una breve descrizione del significato delle
2084 singole opzioni sulla sesta.
2085
2086 Le descrizioni delle opzioni presenti in tab.~\ref{tab:sock_opt_socklevel}
2087 sono estremamente sommarie, è perciò necessario fornire un po' più di
2088 informazioni. Alcune opzioni inoltre hanno una notevole rilevanza nella
2089 gestione dei socket, e pertanto il loro utilizzo sarà approfondito
2090 separatamente in sez.~\ref{sec:sock_options_main}. Quello che segue è quindi
2091 soltanto un elenco più dettagliato della breve descrizione di
2092 tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
2093 \begin{basedescript}{\desclabelwidth{2.5cm}\desclabelstyle{\nextlinelabel}}
2094
2095 \item[\const{SO\_KEEPALIVE}] questa opzione abilita un meccanismo di verifica
2096   della persistenza di una connessione associata al socket (ed è pertanto
2097   effettiva solo sui socket che supportano le connessioni, ed è usata
2098   principalmente con il TCP). L'opzione utilizza per \param{optval} un intero
2099   usato come valore logico. Maggiori dettagli sul suo funzionamento sono
2100   forniti in sez.~\ref{sec:sock_options_main}.
2101
2102 \item[\const{SO\_OOBINLINE}] se questa opzione viene abilitata i dati
2103   \itindex{out-of-band} \textit{out-of-band} vengono inviati direttamente nel
2104   flusso di dati del socket (e sono quindi letti con una normale \func{read})
2105   invece che restare disponibili solo per l'accesso con l'uso del flag
2106   \const{MSG\_OOB} di \func{recvmsg}. L'argomento è trattato in dettaglio in
2107   sez.~\ref{sec:TCP_urgent_data}. L'opzione funziona soltanto con socket che
2108   supportino i dati \itindex{out-of-band} \textit{out-of-band} (non ha senso
2109   per socket UDP ad esempio), ed utilizza per \param{optval} un intero usato
2110   come valore logico.
2111
2112 \item[\const{SO\_RCVLOWAT}] questa opzione imposta il valore che indica il
2113   numero minimo di byte che devono essere presenti nel buffer di ricezione
2114   perché il kernel passi i dati all'utente, restituendoli ad una \func{read} o
2115   segnalando ad una \func{select} (vedi sez.~\ref{sec:TCP_sock_select}) che ci
2116   sono dati in ingresso. L'opzione utilizza per \param{optval} un intero che
2117   specifica il numero di byte, ma con Linux questo valore è sempre 1 e non può
2118   essere cambiato; \func{getsockopt} leggerà questo valore mentre
2119   \func{setsockopt} darà un errore di \errcode{ENOPROTOOPT}. 
2120
2121 \item[\const{SO\_SNDLOWAT}] questa opzione imposta il valore che indica il
2122   numero minimo di byte che devono essere presenti nel buffer di trasmissione
2123   perché il kernel li invii al protocollo successivo, consentendo ad una
2124   \func{write} di ritornare o segnalando ad una \func{select} (vedi
2125   sez.~\ref{sec:TCP_sock_select}) che è possibile eseguire una scrittura.
2126   L'opzione utilizza per \param{optval} un intero che specifica il numero di
2127   byte, come per la precedente \const{SO\_RCVLOWAT} con Linux questo valore è
2128   sempre 1 e non può essere cambiato; \func{getsockopt} leggerà questo valore
2129   mentre \func{setsockopt} darà un errore di \errcode{ENOPROTOOPT}.
2130
2131 \item[\const{SO\_RCVTIMEO}] l'opzione permette di impostare un tempo massimo
2132   sulle operazioni di lettura da un socket, e prende per \param{optval} una
2133   struttura di tipo \struct{timeval} (vedi fig.~\ref{fig:sys_timeval_struct})
2134   identica a quella usata con \func{select}. Con \func{getsockopt} si può
2135   leggere il valore attuale, mentre con \func{setsockopt} si imposta il tempo
2136   voluto, usando un valore nullo per \struct{timeval} il timeout viene
2137   rimosso. 
2138
2139   Se l'opzione viene attivata tutte le volte che una delle funzioni di lettura
2140   (\func{read}, \func{readv}, \func{recv}, \func{recvfrom} e \func{recvmsg})
2141   si blocca in attesa di dati per un tempo maggiore di quello impostato, essa
2142   ritornerà un valore -1 e la variabile \var{errno} sarà impostata con un
2143   errore di \errcode{EAGAIN} e \errcode{EWOULDBLOCK}, così come sarebbe
2144   avvenuto se si fosse aperto il socket in modalità non bloccante.\footnote{in
2145     teoria, se il numero di byte presenti nel buffer di ricezione fosse
2146     inferiore a quello specificato da \const{SO\_RCVLOWAT}, l'effetto potrebbe
2147     essere semplicemente quello di provocare l'uscita delle funzioni di
2148     lettura restituendo il numero di byte fino ad allora ricevuti; dato che
2149     con Linux questo valore è sempre 1 questo caso non esiste.}
2150
2151   In genere questa opzione non è molto utilizzata se si ha a che fare con la
2152   lettura dei dati, in quanto è sempre possibile usare una \func{select} che
2153   consente di specificare un \textit{timeout}; l'uso di \func{select} non
2154   consente però di impostare il timeout per l'uso di \func{connect}, per avere
2155   il quale si può ricorrere a questa opzione. 
2156
2157 % TODO verificare il timeout con un programma di test
2158
2159 \item[\const{SO\_SNDTIMEO}] l'opzione permette di impostare un tempo massimo
2160   sulle operazioni di scrittura su un socket, ed usa gli stessi valori di
2161   \const{SO\_RCVTIMEO}.  In questo caso però si avrà un errore di
2162   \errcode{EAGAIN} o \errcode{EWOULDBLOCK} per le funzioni di scrittura
2163   \func{write}, \func{writev}, \func{send}, \func{sendto} e \func{sendmsg}
2164   qualora queste restino bloccate per un tempo maggiore di quello specificato. 
2165
2166 \item[\const{SO\_BSDCOMPAT}] questa opzione abilita la compatibilità con il
2167   comportamento di BSD (in particolare ne riproduce i bug).  Attualmente è una
2168   opzione usata solo per il protocollo UDP e ne è prevista la rimozione in
2169   futuro.  L'opzione utilizza per \param{optval} un intero usato come valore
2170   logico. 
2171
2172   Quando viene abilitata gli errori riportati da messaggi ICMP per un socket
2173   UDP non vengono passati al programma in user space. Con le versioni 2.0.x
2174   del kernel erano anche abilitate altre opzioni per i socket raw, che sono
2175   state rimosse con il passaggio al 2.2; è consigliato correggere i programmi
2176   piuttosto che usare questa funzione. 
2177
2178 \item[\const{SO\_PASSCRED}] questa opzione abilita sui socket unix-domain
2179   (vedi sez.~\ref{sec:unix_socket}) la ricezione dei messaggi di controllo di
2180   tipo \const{SCM\_CREDENTIALS}. Prende come \param{optval} un intero usato
2181   come valore logico.
2182
2183 \item[\const{SO\_PEERCRED}] questa opzione restituisce le credenziali del
2184   processo remoto connesso al socket; l'opzione è disponibile solo per socket
2185   unix-domain e può essere usata solo con \func{getsockopt}.  Utilizza per
2186   \param{optval} una apposita struttura \struct{ucred} (vedi
2187   sez.~\ref{sec:unix_socket}). 
2188
2189 \item[\const{SO\_BINDTODEVICE}] questa opzione permette di \textsl{legare} il
2190   socket ad una particolare interfaccia, in modo che esso possa ricevere ed
2191   inviare pacchetti solo su quella. L'opzione richiede per \param{optval} il
2192   puntatore ad una stringa contenente il nome dell'interfaccia (ad esempio
2193   \texttt{eth0}); utilizzando una stringa nulla o un valore nullo per
2194   \param{optlen} si può rimuovere un precedente collegamento.
2195
2196   Il nome della interfaccia deve essere specificato con una stringa terminata
2197   da uno zero e di lunghezza massima pari a \const{IFNAMSIZ}; l'opzione è
2198   effettiva solo per alcuni tipi di socket, ed in particolare per quelli della
2199   famiglia \const{AF\_INET}; non è invece supportata per i \textit{packet
2200     socket} (vedi sez.~\ref{sec:socket_raw}). 
2201
2202 \item[\const{SO\_DEBUG}] questa opzione abilita il debugging delle operazioni
2203   dei socket; l'opzione utilizza per \param{optval} un intero usato come
2204   valore logico, e può essere utilizzata solo da un processo con i privilegi
2205   di amministratore (in particolare con la \itindex{capabilities}
2206   \textit{capability} \const{CAP\_NET\_ADMIN}).  L'opzione necessita inoltre
2207   dell'opportuno supporto nel kernel;\footnote{deve cioè essere definita la
2208     macro di preprocessore \macro{SOCK\_DEBUGGING} nel file
2209     \file{include/net/sock.h} dei sorgenti del kernel, questo è sempre vero
2210     nei kernel delle serie superiori alla 2.3, per i kernel delle serie
2211     precedenti invece è necessario aggiungere a mano detta definizione; è
2212     inoltre possibile abilitare anche il tracciamento degli stati del TCP
2213     definendo la macro \macro{STATE\_TRACE} in \file{include/net/tcp.h}.}
2214   quando viene abilitata una serie di messaggi con le informazioni di debug
2215   vengono inviati direttamente al sistema del kernel log.\footnote{si tenga
2216     presente che il comportamento è diverso da quanto avviene con BSD, dove
2217     l'opzione opera solo sui socket TCP, causando la scrittura di tutti i
2218     pacchetti inviati sulla rete su un buffer circolare che viene letto da un
2219     apposito programma, \cmd{trpt}.}
2220
2221 \item[\const{SO\_REUSEADDR}] questa opzione permette di eseguire la funzione
2222   \func{bind} su indirizzi locali che siano già in uso da altri socket;
2223   l'opzione utilizza per \param{optval} un intero usato come valore logico.
2224   Questa opzione modifica il comportamento normale dell'interfaccia dei socket
2225   che fa fallire l'esecuzione della funzione \func{bind} con un errore di
2226   \errcode{EADDRINUSE} quando l'indirizzo locale\footnote{più propriamente il
2227     controllo viene eseguito sulla porta.} è già in uso da parte di un altro
2228   socket.  Maggiori dettagli sul suo funzionamento sono forniti in
2229   sez.~\ref{sec:sock_options_main}.
2230
2231 \item[\const{SO\_TYPE}] questa opzione permette di leggere il tipo di socket
2232   su cui si opera; funziona solo con \func{getsockopt}, ed utilizza per
2233   \param{optval} un intero in cui verrà restituito il valore numerico che lo
2234   identifica (ad esempio \const{SOCK\_STREAM}). 
2235
2236 \item[\const{SO\_ACCEPTCONN}] questa opzione permette di rilevare se il socket
2237   su cui opera è stato posto in modalità di ricezione di eventuali connessioni
2238   con una chiamata a \func{listen}. L'opzione può essere usata soltanto con
2239   \func{getsockopt} e utilizza per \param{optval} un intero in cui viene
2240   restituito 1 se il socket è in ascolto e 0 altrimenti. 
2241
2242 \item[\const{SO\_DONTROUTE}] questa opzione forza l'invio diretto dei
2243   pacchetti del socket, saltando ogni processo relativo all'uso della tabella
2244   di routing del kernel. Prende per \param{optval} un intero usato come valore
2245   logico.
2246
2247 \item[\const{SO\_BROADCAST}] questa opzione abilita il \itindex{broadcast}
2248   \textit{broadcast}; quanto abilitata i socket di tipo \const{SOCK\_DGRAM}
2249   riceveranno i pacchetti inviati all'indirizzo di \textit{broadcast}, e
2250   potranno scrivere pacchetti su tale indirizzo.  Prende per \param{optval} un
2251   intero usato come valore logico. L'opzione non ha effetti su un socket di
2252   tipo \const{SOCK\_STREAM}.
2253
2254 \item[\const{SO\_SNDBUF}] questa opzione imposta la dimensione del buffer di
2255   trasmissione del socket. Prende per \param{optval} un intero indicante il
2256   numero di byte. Il valore di default ed il valore massimo che si possono
2257   specificare come argomento per questa opzione sono impostabili
2258   rispettivamente tramite gli opportuni valori di \func{sysctl} (vedi
2259   sez.~\ref{sec:sock_sysctl}).
2260
2261 \item[\const{SO\_RCVBUF}] questa opzione imposta la dimensione del buffer di
2262   ricezione del socket. Prende per \param{optval} un intero indicante il
2263   numero di byte. Il valore di default ed il valore massimo che si può
2264   specificare come argomento per questa opzione sono impostabili tramiti gli
2265   opportuni valori di \func{sysctl} (vedi sez.~\ref{sec:sock_sysctl}).
2266
2267   Si tenga presente che nel caso di socket TCP, per entrambe le opzioni
2268   \const{SO\_RCVBUF} e \const{SO\_SNDBUF}, il kernel alloca effettivamente una
2269   quantità di memoria doppia rispetto a quanto richiesto con
2270   \func{setsockopt}. Questo comporta che una successiva lettura con
2271   \func{getsockopt} riporterà un valore diverso da quello impostato con
2272   \func{setsockopt}.  Questo avviene perché TCP necessita dello spazio in più
2273   per mantenere dati amministrativi e strutture interne, e solo una parte
2274   viene usata come buffer per i dati, mentre il valore letto da
2275   \func{getsockopt} e quello riportato nei vari parametri di
2276   \textit{sysctl}\footnote{cioè \procrelfile{/proc/sys/net/core}{wmem\_max} e
2277     \procrelfile{/proc/sys/net/core}{rmem\_max} in \texttt{/proc/sys/net/core}
2278     e \procrelfile{/proc/sys/net/ipv4}{tcp\_wmem} e
2279     \procrelfile{/proc/sys/net/ipv4}{tcp\_rmem} in
2280     \texttt{/proc/sys/net/ipv4}, vedi sez.~\ref{sec:sock_sysctl}.} indica la
2281   memoria effettivamente impiegata.  Si tenga presente inoltre che le
2282   modifiche alle dimensioni dei buffer di ricezione e trasmissione, per poter
2283   essere effettive, devono essere impostate prima della chiamata alle funzioni
2284   \func{listen} o \func{connect}.
2285
2286 \item[\const{SO\_LINGER}] questa opzione controlla le modalità con cui viene
2287   chiuso un socket quando si utilizza un protocollo che supporta le
2288   connessioni (è pertanto usata con i socket TCP ed ignorata per UDP) e
2289   modifica il comportamento delle funzioni \func{close} e \func{shutdown}.
2290   L'opzione richiede che l'argomento \param{optval} sia una struttura di tipo
2291   \struct{linger}, definita in \texttt{sys/socket.h} ed illustrata in
2292   fig.~\ref{fig:sock_linger_struct}.  Maggiori dettagli sul suo funzionamento
2293   sono forniti in sez.~\ref{sec:sock_options_main}.
2294
2295 \item[\const{SO\_PRIORITY}] questa opzione permette di impostare le priorità
2296   per tutti i pacchetti che sono inviati sul socket, prende per \param{optval}
2297   un valore intero. Con questa opzione il kernel usa il valore per ordinare le
2298   priorità sulle code di rete,\footnote{questo richiede che sia abilitato il
2299     sistema di \textit{Quality of Service} disponibile con le opzioni di
2300     routing avanzato.} i pacchetti con priorità più alta vengono processati
2301   per primi, in modalità che dipendono dalla disciplina di gestione della
2302   coda. Nel caso di protocollo IP questa opzione permette anche di impostare i
2303   valori del campo \textit{type of service} (noto come TOS, vedi
2304   sez.~\ref{sec:IP_header}) per i pacchetti uscenti. Per impostare una
2305   priorità al di fuori dell'intervallo di valori fra 0 e 6 sono richiesti i
2306   privilegi di amministratore con la \itindex{capabilities} capability
2307   \const{CAP\_NET\_ADMIN}.
2308
2309 \item[\const{SO\_ERROR}] questa opzione riceve un errore presente sul socket;
2310   può essere utilizzata soltanto con \func{getsockopt} e prende per
2311   \param{optval} un valore intero, nel quale viene restituito il codice di
2312   errore, e la condizione di errore sul socket viene cancellata. Viene
2313   usualmente utilizzata per ricevere il codice di errore, come accennato in
2314   sez.~\ref{sec:TCP_sock_select}, quando si sta osservando il socket con una
2315   \func{select} che ritorna a causa dello stesso.
2316
2317 \item[\const{SO\_ATTACH\_FILTER}] questa opzione permette di agganciare ad un
2318   socket un filtro di pacchetti che consente di selezionare quali pacchetti,
2319   fra tutti quelli ricevuti, verranno letti. Viene usato principalmente con i
2320   socket di tipo \const{PF\_PACKET} con la libreria \texttt{libpcap} per
2321   implementare programmi di cattura dei pacchetti, torneremo su questo in
2322   sez.~\ref{sec:packet_socket}.
2323
2324 \item[\const{SO\_DETACH\_FILTER}] consente di distaccare un filtro
2325   precedentemente aggiunto ad un socket.
2326
2327 % TODO documentare SO_ATTACH_FILTER e SO_DETACH_FILTER
2328 % riferimenti http://www.rcpt.to/lsfcc/lsf.html
2329 % Documentation/networking/filter.txt
2330
2331 % TODO documentare SO_MARK, introdotta nel 2.6.25, richiede CAP_NET_ADMIN
2332 %A userspace program may wish to set the mark for each packets its send
2333 %without using the netfilter MARK target. Changing the mark can be used
2334 %for mark based routing without netfilter or for packet filtering.
2335
2336
2337 % TODO documentare SO_TIMESTAMP e le altre opzioni di timestamping dei 
2338 % pacchetti, introdotte nel 2.6.30, vedi nei sorgenti del kernel:
2339 % Documentation/networking/timestamping.txt
2340
2341
2342 \end{basedescript}
2343
2344
2345 \subsection{L'uso delle principali opzioni dei socket}
2346 \label{sec:sock_options_main}
2347
2348 La descrizione sintetica del significato delle opzioni generiche dei socket,
2349 riportata nell'elenco in sez.~\ref{sec:sock_generic_options}, è
2350 necessariamente sintetica, alcune di queste però possono essere utilizzate
2351 per controllare delle funzionalità che hanno una notevole rilevanza nella
2352 programmazione dei socket.  Per questo motivo faremo in questa sezione un
2353 approfondimento sul significato delle opzioni generiche più importanti.
2354
2355
2356 \index{costante!{SO\_KEEPALIVE}@{{\tt  {SO\_KEEPALIVE}}}|(}
2357 \subsubsection{L'opzione \const{SO\_KEEPALIVE}}
2358
2359 La prima opzione da approfondire è \const{SO\_KEEPALIVE} che permette di
2360 tenere sotto controllo lo stato di una connessione. Una connessione infatti
2361 resta attiva anche quando non viene effettuato alcun traffico su di essa; è
2362 allora possibile, in caso di una interruzione completa della rete, che la
2363 caduta della connessione non venga rilevata, dato che sulla stessa non passa
2364 comunque alcun traffico.
2365
2366 Se si imposta questa opzione, è invece cura del kernel inviare degli appositi
2367 messaggi sulla rete, detti appunto \textit{keep-alive}, per verificare se la
2368 connessione è attiva.  L'opzione funziona soltanto con i socket che supportano
2369 le connessioni (non ha senso per socket UDP ad esempio) e si applica
2370 principalmente ai socket TCP.
2371
2372 Con le impostazioni di default (che sono riprese da BSD) Linux emette un
2373 messaggio di \textit{keep-alive}\footnote{in sostanza un segmento ACK vuoto,
2374   cui sarà risposto con un altro segmento ACK vuoto.} verso l'altro capo della
2375 connessione se questa è rimasta senza traffico per più di due ore.  Se è tutto
2376 a posto il messaggio viene ricevuto e verrà emesso un segmento ACK di
2377 risposta, alla cui ricezione ripartirà un altro ciclo di attesa per altre due
2378 ore di inattività; il tutto avviene all'interno del kernel e le applicazioni
2379 non riceveranno nessun dato.
2380
2381 Qualora ci siano dei problemi di rete si possono invece verificare i due casi
2382 di terminazione precoce del server già illustrati in
2383 sez.~\ref{sec:TCP_conn_crash}. Il primo è quello in cui la macchina remota ha
2384 avuto un crollo del sistema ed è stata riavviata, per cui dopo il riavvio la
2385 connessione non esiste più.\footnote{si ricordi che un normale riavvio o il
2386   crollo dell'applicazione non ha questo effetto, in quanto in tal caso si
2387   passa sempre per la chiusura del processo, e questo, come illustrato in
2388   sez.~\ref{sec:file_close}, comporta anche la regolare chiusura del socket
2389   con l'invio di un segmento FIN all'altro capo della connessione.} In questo
2390 caso all'invio del messaggio di \textit{keep-alive} si otterrà come risposta
2391 un segmento RST che indica che l'altro capo non riconosce più l'esistenza
2392 della connessione ed il socket verrà chiuso riportando un errore di
2393 \errcode{ECONNRESET}.
2394
2395 Se invece non viene ricevuta nessuna risposta (indice che la macchina non è
2396 più raggiungibile) l'emissione dei messaggi viene ripetuta ad intervalli di 75
2397 secondi per un massimo di 9 volte\footnote{entrambi questi valori possono
2398   essere modificati a livello di sistema (cioè per tutti i socket) con gli
2399   opportuni parametri illustrati in sez.~\ref{sec:sock_sysctl} ed a livello di
2400   singolo socket con le opzioni \texttt{TCP\_KEEP*} di
2401   sez.~\ref{sec:sock_tcp_udp_options}.}  (per un totale di 11 minuti e 15
2402 secondi) dopo di che, se non si è ricevuta nessuna risposta, il socket viene
2403 chiuso dopo aver impostato un errore di \errcode{ETIMEDOUT}. Qualora la
2404 connessione si sia ristabilita e si riceva un successivo messaggio di risposta
2405 il ciclo riparte come se niente fosse avvenuto.  Infine se si riceve come
2406 risposta un pacchetto ICMP di destinazione irraggiungibile (vedi
2407 sez.~\ref{sec:ICMP_protocol}), verrà restituito l'errore corrispondente.
2408
2409 In generale questa opzione serve per individuare una caduta della connessione
2410 anche quando non si sta facendo traffico su di essa.  Viene usata
2411 principalmente sui server per evitare di mantenere impegnate le risorse che
2412 verrebbero dedicate a trattare delle connessioni che in realtà sono già
2413 terminate (quelle che vengono anche chiamate connessioni
2414 \textsl{semi-aperte}); in tutti quei casi cioè in cui il server si trova in
2415 attesa di dati in ingresso su una connessione che non arriveranno mai o perché
2416 il client sull'altro capo non è più attivo o perché non è più in grado di
2417 comunicare con il server via rete.
2418
2419 \begin{figure}[!htb]
2420   \footnotesize \centering
2421   \begin{minipage}[c]{15cm}
2422     \includecodesample{listati/TCP_echod_fourth.c}
2423   \end{minipage}
2424   \normalsize
2425   \caption{La sezione della nuova versione del server del servizio
2426     \textit{echo} che prevede l'attivazione del \textit{keepalive} sui
2427     socket.}
2428   \label{fig:echod_keepalive_code}
2429 \end{figure}
2430
2431 Abilitandola dopo un certo tempo le connessioni effettivamente terminate
2432 verranno comunque chiuse per cui, utilizzando ad esempio una \func{select}, se
2433 be potrà rilevare la conclusione e ricevere il relativo errore. Si tenga
2434 presente però che non può avere la certezza assoluta che un errore di
2435 \errcode{ETIMEDOUT} ottenuto dopo aver abilitato questa opzione corrisponda
2436 necessariamente ad una reale conclusione della connessione, il problema
2437 potrebbe anche essere dovuto ad un problema di routing che perduri per un
2438 tempo maggiore di quello impiegato nei vari tentativi di ritrasmissione del
2439 \textit{keep-alive} (anche se questa non è una condizione molto probabile).
2440
2441 Come esempio dell'utilizzo di questa opzione introduciamo all'interno del
2442 nostro server per il servizio \textit{echo} la nuova opzione \texttt{-k} che
2443 permette di attivare il \textit{keep-alive} sui socket; tralasciando la parte
2444 relativa alla gestione di detta opzione (che si limita ad assegnare ad 1 la
2445 variabile \var{keepalive}) tutte le modifiche al server sono riportate in
2446 fig.~\ref{fig:echod_keepalive_code}. Al solito il codice completo è contenuto
2447 nel file \texttt{TCP\_echod\_fourth.c} dei sorgenti allegati alla guida.
2448
2449 Come si può notare la variabile \var{keepalive} è preimpostata (\texttt{\small
2450   8}) ad un valore nullo; essa viene utilizzata sia come variabile logica per
2451 la condizione (\texttt{\small 14}) che controlla l'attivazione del
2452 \textit{keep-alive} che come valore dell'argomento \param{optval} della
2453 chiamata a \func{setsockopt} (\texttt{\small 16}).  A seconda del suo valore
2454 tutte le volte che un processo figlio viene eseguito in risposta ad una
2455 connessione verrà pertanto eseguita o meno la sezione (\texttt{\small 14--17})
2456 che esegue l'impostazione di \const{SO\_KEEPALIVE} sul socket connesso,
2457 attivando il relativo comportamento.
2458 \index{costante!{SO\_KEEPALIVE}@{{\tt  {SO\_KEEPALIVE}}}|)}
2459
2460
2461
2462 \index{costante!{SO\_REUSEADDR}@{{\tt  {SO\_REUSEADDR}}}|(}
2463 \subsubsection{L'opzione \const{SO\_REUSEADDR}}
2464
2465 La seconda opzione da approfondire è \const{SO\_REUSEADDR}, che consente di
2466 eseguire \func{bind} su un socket anche quando la porta specificata è già in
2467 uso da parte di un altro socket. Si ricordi infatti che, come accennato in
2468 sez.~\ref{sec:TCP_func_bind}, normalmente la funzione \func{bind} fallisce con
2469 un errore di \errcode{EADDRINUSE} se la porta scelta è già utilizzata da un
2470 altro socket, proprio per evitare che possano essere lanciati due server sullo
2471 stesso indirizzo e la stessa porta, che verrebbero a contendersi i pacchetti
2472 aventi quella destinazione.
2473
2474 Esistono però situazioni ed esigenze particolari in cui non si vuole che
2475 questo comportamento di salvaguardia accada, ed allora si può fare ricorso a
2476 questa opzione.  La questione è comunque abbastanza complessa in quanto, come
2477 sottolinea Stevens in \cite{UNP1}, si distinguono ben quattro casi diversi in
2478 cui è prevista la possibilità di un utilizzo di questa opzione, il che la
2479 rende una delle più difficili da capire.
2480
2481 Il primo caso, che è anche il più comune, in cui si fa ricorso a
2482 \const{SO\_REUSEADDR} è quello in cui un server è terminato ma esistono ancora
2483 dei processi figli che mantengono attiva almeno una connessione remota che
2484 utilizza l'indirizzo locale, mantenendo occupata la porta. Quando si riesegue
2485 il server allora questo riceve un errore sulla chiamata a \func{bind} dato che
2486 la porta è ancora utilizzata in una connessione esistente.\footnote{questa è
2487   una delle domande più frequenti sui newsgroup dedicati allo sviluppo, in
2488   quanto è piuttosto comune trovarsi in questa situazione quando si sta
2489   sviluppando un server che si ferma e si riavvia in continuazione dopo aver
2490   fatto modifiche.}  Inoltre se si usa il protocollo TCP questo può avvenire
2491 anche dopo tutti i processi figli sono terminati, dato che una connessione può
2492 restare attiva anche dopo la chiusura del socket, mantenendosi nello stato
2493 \texttt{TIME\_WAIT} (vedi sez.~\ref{sec:TCP_time_wait}).
2494
2495 Usando \const{SO\_REUSEADDR} fra la chiamata a \func{socket} e quella a
2496 \func{bind} si consente a quest'ultima di avere comunque successo anche se la
2497 connessione è attiva (o nello stato \texttt{TIME\_WAIT}). È bene però
2498 ricordare (si riveda quanto detto in sez.~\ref{sec:TCP_time_wait}) che la
2499 presenza dello stato \texttt{TIME\_WAIT} ha una ragione, ed infatti se si usa
2500 questa opzione esiste sempre una probabilità, anche se estremamente
2501 remota,\footnote{perché ciò avvenga infatti non solo devono coincidere gli
2502   indirizzi IP e le porte degli estremi della nuova connessione, ma anche i
2503   numeri di sequenza dei pacchetti, e questo è estremamente improbabile.}  che
2504 eventuali pacchetti rimasti intrappolati in una precedente connessione possano
2505 finire fra quelli di una nuova.
2506
2507 Come esempio di uso di questa connessione abbiamo predisposto una nuova
2508 versione della funzione \func{sockbind} (vedi fig.~\ref{fig:sockbind_code})
2509 che consenta l'impostazione di questa opzione. La nuova funzione è
2510 \func{sockbindopt}, e le principali differenze rispetto alla precedente sono
2511 illustrate in fig.~\ref{fig:sockbindopt_code}, dove si sono riportate le
2512 sezioni di codice modificate rispetto alla versione precedente. Il codice
2513 completo della funzione si trova, insieme alle altre funzioni di servizio dei
2514 socket, all'interno del file \texttt{SockUtils.c} dei sorgenti allegati alla
2515 guida.
2516
2517 \begin{figure}[!htb]
2518   \footnotesize \centering
2519   \begin{minipage}[c]{15cm}
2520     \includecodesample{listati/sockbindopt.c}
2521   \end{minipage}
2522   \normalsize
2523   \caption{Le sezioni della funzione \func{sockbindopt} modificate rispetto al
2524     codice della precedente \func{sockbind}.} 
2525   \label{fig:sockbindopt_code}
2526 \end{figure}
2527
2528 In realtà tutto quello che si è fatto è stato introdurre nella nuova funzione
2529 (\texttt{\small 1}) un nuovo argomento intero, \param{reuse}, che conterrà il
2530 valore logico da usare nella successiva chiamata (\texttt{\small 14}) a
2531 \func{setsockopt}. Si è poi aggiunta una sezione (\texttt{\small 13-17}) che
2532 esegue l'impostazione dell'opzione fra la chiamata a \func{socket} e quella a
2533 \func{bind}.
2534
2535
2536 A questo punto basterà modificare il  server per utilizzare la nuova
2537 funzione; in fig.~\ref{fig:TCP_echod_fifth} abbiamo riportato le sezioni
2538 modificate rispetto alla precedente versione di
2539 fig.~\ref{fig:TCP_echod_third}. Al solito il codice completo è coi sorgenti
2540 allegati alla guida, nel file \texttt{TCP\_echod\_fifth.c}.
2541
2542 Anche in questo caso si è introdotta (\texttt{\small 8}) una nuova variabile
2543 \var{reuse} che consente di controllare l'uso dell'opzione e che poi sarà
2544 usata (\texttt{\small 14}) come ultimo argomento di \func{setsockopt}. Il
2545 valore di default di questa variabile è nullo, ma usando l'opzione \texttt{-r}
2546 nell'invocazione del server (al solito la gestione delle opzioni non è
2547 riportata in fig.~\ref{fig:TCP_echod_fifth}) se ne potrà impostare ad 1 il
2548 valore, per cui in tal caso la successiva chiamata (\texttt{\small 13-17}) a
2549 \func{setsockopt} attiverà l'opzione \const{SO\_REUSEADDR}.
2550
2551 \begin{figure}[!htb] 
2552   \footnotesize \centering
2553   \begin{minipage}[c]{15cm}
2554     \includecodesample{listati/TCP_echod_fifth.c}
2555   \end{minipage}
2556   \normalsize
2557   \caption{Il nuovo codice per l'apertura passiva del server \textit{echo} che
2558     usa la nuova funzione \func{sockbindopt}.}
2559   \label{fig:TCP_echod_fifth}
2560 \end{figure}
2561
2562 Il secondo caso in cui viene usata \const{SO\_REUSEADDR} è quando si ha una
2563 macchina cui sono assegnati diversi numeri IP (o come suol dirsi
2564 \textit{multi-homed}) e si vuole porre in ascolto sulla stessa porta un
2565 programma diverso (o una istanza diversa dello stesso programma) per indirizzi
2566 IP diversi. Si ricordi infatti che è sempre possibile indicare a \func{bind}
2567 di collegarsi solo su di un indirizzo specifico; in tal caso se un altro
2568 programma cerca di riutilizzare la stessa porta (anche specificando un
2569 indirizzo diverso) otterrà un errore, a meno di non aver preventivamente
2570 impostato \const{SO\_REUSEADDR}.
2571
2572 Usando questa opzione diventa anche possibile eseguire \func{bind}
2573 sull'indirizzo generico, e questo permetterà il collegamento per tutti gli
2574 indirizzi (di quelli presenti) per i quali la porta non risulti occupata da
2575 una precedente chiamata più specifica. Infine si tenga presente che con il
2576 protocollo TCP non è mai possibile far partire server che eseguano \func{bind}
2577 sullo stesso indirizzo e la stessa porta, cioè ottenere quello che viene
2578 chiamato un \textit{completely duplicate binding}.
2579
2580 Il terzo impiego è simile al precedente e prevede l'uso di \func{bind}
2581 all'interno dello stesso programma per associare indirizzi locali diversi a
2582 socket diversi. In genere questo viene fatto per i socket UDP quando è
2583 necessario ottenere l'indirizzo a cui sono rivolte le richieste del client ed
2584 il sistema non supporta l'opzione \const{IP\_RECVDSTADDR};\footnote{nel caso
2585   di Linux questa opzione è stata supportata per in certo periodo nello
2586   sviluppo del kernel 2.1.x, ma è in seguito stata soppiantata dall'uso di
2587   \const{IP\_PKTINFO} (vedi sez.~\ref{sec:sock_ipv4_options}).} in tale modo
2588 si può sapere a quale socket corrisponde un certo indirizzo.  Non ha senso
2589 fare questa operazione per un socket TCP dato che su di essi si può sempre
2590 invocare \func{getsockname} una volta che si è completata la connessione.
2591
2592 Infine il quarto caso è quello in cui si vuole effettivamente ottenere un
2593 \textit{completely duplicate binding}, quando cioè si vuole eseguire
2594 \func{bind} su un indirizzo ed una porta che sono già \textsl{legati} ad un
2595 altro socket.  Questo ovviamente non ha senso per il normale traffico di rete,
2596 in cui i pacchetti vengono scambiati direttamente fra due applicazioni; ma
2597 quando un sistema supporta il traffico in \itindex{multicast}
2598 \textit{multicast}, in cui una applicazione invia i pacchetti a molte altre
2599 (vedi sez.~\ref{sec:xxx_multicast}), allora ha senso che su una macchina i
2600 pacchetti provenienti dal traffico in \itindex{multicast} \textit{multicast}
2601 possano essere ricevuti da più applicazioni\footnote{l'esempio classico di
2602   traffico in \textit{multicast} è quello di uno streaming di dati (audio,
2603   video, ecc.), l'uso del \textit{multicast} consente in tal caso di
2604   trasmettere un solo pacchetto, che potrà essere ricevuto da tutti i
2605   possibili destinatari (invece di inviarne un duplicato a ciascuno); in
2606   questo caso è perfettamente logico aspettarsi che sulla stessa macchina più
2607   utenti possano lanciare un programma che permetta loro di ricevere gli
2608   stessi dati.} o da diverse istanze della stessa applicazione.
2609 \itindex{multicast}
2610
2611 In questo caso utilizzando \const{SO\_REUSEADDR} si consente ad una
2612 applicazione eseguire \func{bind} sulla stessa porta ed indirizzo usata da
2613 un'altra, così che anche essa possa ricevere gli stessi pacchetti (chiaramente
2614 la cosa non ha alcun senso per i socket TCP, ed infatti in questo tipo di
2615 applicazione è normale l'uso del protocollo UDP). La regola è che quando si
2616 hanno più applicazioni che hanno eseguito \func{bind} sulla stessa porta, di
2617 tutti pacchetti destinati ad un indirizzo di \itindex{broadcast}
2618 \textit{broadcast} o di \itindex{multicast} \textit{multicast} viene inviata
2619 una copia a ciascuna applicazione.  Non è definito invece cosa accade qualora
2620 il pacchetto sia destinato ad un indirizzo normale (unicast).
2621
2622 Essendo questo un caso particolare in alcuni sistemi (come BSD) è stata
2623 introdotta una opzione ulteriore, \const{SO\_REUSEPORT} che richiede che detta
2624 opzione sia specificata per tutti i socket per i quali si vuole eseguire il
2625 \textit{completely duplicate binding}. Nel caso di Linux questa opzione non
2626 esiste, ma il comportamento di \const{SO\_REUSEADDR} è analogo, sarà cioè
2627 possibile effettuare un \textit{completely duplicate binding} ed ottenere il
2628 successo di \func{bind} su un socket legato allo stesso indirizzo e porta solo
2629 se il programma che ha eseguito per primo \func{bind} su di essi ha impostato
2630 questa opzione.\footnote{questa restrizione permette di evitare il cosiddetto
2631   \textit{port stealing}, in cui un programma, usando \const{SO\_REUSEADDR},
2632   può collegarsi ad una porta già in uso e ricevere i pacchetti destinati ad
2633   un altro programma; con questa caratteristica ciò è possibile soltanto se il
2634   primo programma a consentirlo, avendo usato fin dall'inizio
2635   \const{SO\_REUSEADDR}.}  
2636
2637 \index{costante!{SO\_REUSEADDR}@{{\tt  {SO\_REUSEADDR}}}|)}
2638
2639 \index{costante!{SO\_LINGER}@{{\tt  {SO\_LINGER}}}|(}
2640 \subsubsection{L'opzione \const{SO\_LINGER}}
2641
2642 La terza opzione da approfondire è \const{SO\_LINGER}; essa, come il nome
2643 suggerisce, consente di ``\textsl{indugiare}'' nella chiusura di un socket. Il
2644 comportamento standard sia di \func{close} che \func{shutdown} è infatti
2645 quello di terminare immediatamente dopo la chiamata, mentre il procedimento di
2646 chiusura della connessione (o di un lato di essa) ed il rispettivo invio sulla
2647 rete di tutti i dati ancora presenti nei buffer, viene gestito in sottofondo
2648 dal kernel.
2649
2650 \begin{figure}[!htb]
2651   \footnotesize \centering
2652   \begin{minipage}[c]{15cm}
2653     \includestruct{listati/linger.h}
2654   \end{minipage}
2655   \caption{La struttura \structd{linger} richiesta come valore dell'argomento
2656     \param{optval} per l'impostazione dell'opzione dei socket
2657     \const{SO\_LINGER}.}
2658   \label{fig:sock_linger_struct}
2659 \end{figure}
2660
2661 L'uso di \const{SO\_LINGER} con \func{setsockopt} permette di modificare (ed
2662 eventualmente ripristinare) questo comportamento in base ai valori passati nei
2663 campi della struttura \struct{linger}, illustrata in
2664 fig.~\ref{fig:sock_linger_struct}.  Fintanto che il valore del campo
2665 \var{l\_onoff} di \struct{linger} è nullo la modalità che viene impostata
2666 (qualunque sia il valore di \var{l\_linger}) è quella standard appena
2667 illustrata; questa combinazione viene utilizzata per riportarsi al
2668 comportamento normale qualora esso sia stato cambiato da una precedente
2669 chiamata.
2670
2671 Se si utilizza un valore di \var{l\_onoff} diverso da zero, il comportamento
2672 alla chiusura viene a dipendere dal valore specificato per il campo
2673 \var{l\_linger}; se quest'ultimo è nullo l'uso delle funzioni \func{close} e
2674 \func{shutdown} provoca la terminazione immediata della connessione: nel caso
2675 di TCP cioè non viene eseguito il procedimento di chiusura illustrato in
2676 sez.~\ref{sec:TCP_conn_term}, ma tutti i dati ancora presenti nel buffer
2677 vengono immediatamente scartati e sulla rete viene inviato un segmento di RST
2678 che termina immediatamente la connessione.
2679
2680 Un esempio di questo comportamento si può abilitare nel nostro client del
2681 servizio \textit{echo} utilizzando l'opzione \texttt{-r}; riportiamo in
2682 fig.~\ref{fig:TCP_echo_sixth} la sezione di codice che permette di introdurre
2683 questa funzionalità,; al solito il codice completo è disponibile nei sorgenti
2684 allegati.
2685
2686 \begin{figure}[!htb] 
2687   \footnotesize \centering
2688   \begin{minipage}[c]{15cm}
2689     \includecodesample{listati/TCP_echo_sixth.c}
2690   \end{minipage}
2691   \normalsize
2692   \caption{La sezione del codice del client \textit{echo} che imposta la
2693     terminazione immediata della connessione in caso di chiusura.}
2694   \label{fig:TCP_echo_sixth}
2695 \end{figure}
2696
2697 La sezione indicata viene eseguita dopo aver effettuato la connessione e prima
2698 di chiamare la funzione di gestione, cioè fra le righe (\texttt{\small 12}) e
2699 (\texttt{\small 13}) del precedente esempio di fig.~\ref{fig:TCP_echo_fifth}.
2700 Il codice si limita semplicemente a controllare (\texttt{\small 3}) il
2701 valore della variabile \var{reset} che assegnata nella gestione delle opzioni
2702 in corrispondenza all'uso di \texttt{-r} nella chiamata del client. Nel caso
2703 questa sia diversa da zero vengono impostati (\texttt{\small 5--6}) i valori
2704 della struttura \var{ling} che permettono una terminazione immediata della
2705 connessione. Questa viene poi usata nella successiva (\texttt{\small 7})
2706 chiamata a \func{setsockopt}. Al solito si controlla (\texttt{\small 7--10})
2707 il valore di ritorno e si termina il programma in caso di errore, stampandone
2708 il valore.
2709
2710 Infine l'ultima possibilità, quella in cui si utilizza effettivamente
2711 \const{SO\_LINGER} per \textsl{indugiare} nella chiusura, è quella in cui sia
2712 \var{l\_onoff} che \var{l\_linger} hanno un valore diverso da zero. Se si
2713 esegue l'impostazione con questi valori sia \func{close} che \func{shutdown}
2714 si bloccano, nel frattempo viene eseguita la normale procedura di conclusione
2715 della connessione (quella di sez.~\ref{sec:TCP_conn_term}) ma entrambe le
2716 funzioni non ritornano fintanto che non si sia concluso il procedimento di
2717 chiusura della connessione, o non sia passato un numero di
2718 secondi\footnote{questa è l'unità di misura indicata da POSIX ed adottata da
2719   Linux, altri kernel possono usare unità di misura diverse, oppure usare il
2720   campo \var{l\_linger} come valore logico (ignorandone il valore) per rendere
2721   (quando diverso da zero) \func{close} e \func{shutdown} bloccanti fino al
2722   completamento della trasmissione dei dati sul buffer.}  pari al valore
2723 specificato in \var{l\_linger}.
2724
2725 \index{costante!{SO\_LINGER}@{{\tt  {SO\_LINGER}}}|)}
2726
2727
2728
2729 \subsection{Le opzioni per il protocollo IPv4}
2730 \label{sec:sock_ipv4_options}
2731
2732 Il secondo insieme di opzioni dei socket che tratteremo è quello relativo ai
2733 socket che usano il protocollo IPv4.\footnote{come per le precedenti opzioni
2734   generiche una descrizione di esse è disponibile nella settima sezione delle
2735   pagine di manuale, nel caso specifico la documentazione si può consultare
2736   con \texttt{man 7 ip}.}  Se si vuole operare su queste opzioni generiche il
2737 livello da utilizzare è \const{SOL\_IP} (o l'equivalente \const{IPPROTO\_IP});
2738 si è riportato un elenco di queste opzioni in tab.~\ref{tab:sock_opt_iplevel}.
2739 Le costanti indicanti le opzioni e tutte le altre costanti ad esse collegate
2740 sono definite in \file{netinet/ip.h}, ed accessibili includendo detto file.
2741
2742 \begin{table}[!htb]
2743   \centering
2744   \footnotesize
2745   \begin{tabular}[c]{|l|c|c|c|l|l|}
2746     \hline
2747     \textbf{Opzione}&\texttt{get}&\texttt{set}&\textbf{flag}&\textbf{Tipo}&
2748                     \textbf{Descrizione}\\
2749     \hline
2750     \hline
2751     \const{IP\_OPTIONS}         &$\bullet$&$\bullet$&&\texttt{void *}& %??? 
2752       Imposta o riceve le opzioni di IP.\\
2753     \const{IP\_PKTINFO}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2754       Passa un messaggio di informazione.\\
2755     \const{IP\_RECVTOS}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2756       Passa un messaggio col campo TOS.\\
2757     \const{IP\_RECVTTL}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2758       Passa un messaggio col campo TTL.\\
2759     \const{IP\_RECVOPTS}        &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2760       Passa un messaggio con le opzioni IP.\\
2761     \const{IP\_RETOPTS}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2762       Passa un messaggio con le opzioni IP non trattate.\\
2763     \const{IP\_TOS}             &$\bullet$&$\bullet$&         &\texttt{int}& 
2764       Imposta il valore del campo TOS.\\
2765     \const{IP\_TTL}             &$\bullet$&$\bullet$&         &\texttt{int}& 
2766       Imposta il valore del campo TTL.\\
2767     \const{IP\_MINTTL}          &$\bullet$&$\bullet$&   &\texttt{int}& 
2768       Imposta il valore minimo del TTL per i pacchetti accettati.\\ 
2769     \const{IP\_HDRINCL}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2770       Passa l'intestazione di IP nei dati.\\
2771     \const{IP\_RECVERR}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2772       Abilita la gestione degli errori.\\
2773     \const{IP\_MTU\_DISCOVER}   &$\bullet$&$\bullet$&         &\texttt{int}& 
2774       Imposta il Path MTU \itindex{Maximum~Transfer~Unit} Discovery.\\
2775     \const{IP\_MTU}             &$\bullet$&         &         &\texttt{int}& 
2776       Legge il valore attuale della \itindex{Maximum~Transfer~Unit} MTU.\\
2777     \const{IP\_ROUTER\_ALERT}   &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2778       Imposta l'opzione \textit{IP router alert} sui pacchetti.\\
2779     \const{IP\_MULTICAST\_TTL}  &$\bullet$&$\bullet$&         &\texttt{int}& 
2780       Imposta il TTL per i pacchetti \itindex{multicast} \textit{multicast}.\\
2781     \const{IP\_MULTICAST\_LOOP} &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
2782       Controlla il reinvio a se stessi dei dati di \itindex{multicast} 
2783       \textit{multicast}.\\ 
2784     \const{IP\_ADD\_MEMBERSHIP} &         &$\bullet$&   &\struct{ip\_mreqn}& 
2785       Si unisce a un gruppo di \itindex{multicast} \textit{multicast}.\\
2786     \const{IP\_DROP\_MEMBERSHIP}&         &$\bullet$&   &\struct{ip\_mreqn}& 
2787       Si sgancia da un gruppo di \textit{multicast}.\\
2788     \const{IP\_MULTICAST\_IF}   &         &$\bullet$&   &\struct{ip\_mreqn}& 
2789       Imposta l'interfaccia locale di un socket \itindex{multicast} 
2790       \textit{multicast}.\\ 
2791    \hline
2792   \end{tabular}
2793   \caption{Le opzioni disponibili al livello \const{SOL\_IP}.} 
2794   \label{tab:sock_opt_iplevel}
2795 \end{table}
2796
2797 Le descrizioni riportate in tab.~\ref{tab:sock_opt_iplevel} sono estremamente
2798 succinte, una maggiore quantità di dettagli sulle varie opzioni è fornita nel
2799 seguente elenco:
2800 \begin{basedescript}{\desclabelwidth{2.5cm}\desclabelstyle{\nextlinelabel}}
2801
2802
2803 \item[\const{IP\_OPTIONS}] l'opzione permette di impostare o leggere le
2804   opzioni del protocollo IP (si veda sez.~\ref{sec:IP_options}). L'opzione
2805   prende come valore dell'argomento \param{optval} un puntatore ad un buffer
2806   dove sono mantenute le opzioni, mentre \param{optlen} indica la dimensione
2807   di quest'ultimo. Quando la si usa con \func{getsockopt} vengono lette le
2808   opzioni IP utilizzate per la spedizione, quando la si usa con
2809   \func{setsockopt} vengono impostate le opzioni specificate. L'uso di questa
2810   opzione richiede una profonda conoscenza del funzionamento del protocollo,
2811   torneremo in parte sull'argomento in sez.~\ref{sec:sock_IP_options}.
2812
2813
2814 \item[\const{IP\_PKTINFO}] Quando abilitata l'opzione permette di ricevere
2815   insieme ai pacchetti un messaggio ancillare (vedi
2816   sez.~\ref{sec:net_ancillary_data}) di tipo \const{IP\_PKTINFO} contenente
2817   una struttura \struct{pktinfo} (vedi fig.~\ref{fig:sock_pktinfo_struct}) che
2818   mantiene una serie di informazioni riguardo i pacchetti in arrivo. In
2819   particolare è possibile conoscere l'interfaccia su cui è stato ricevuto un
2820   pacchetto (nel campo \var{ipi\_ifindex}),\footnote{in questo campo viene
2821     restituito il valore numerico dell'indice dell'interfaccia,
2822     sez.~\ref{sec:sock_ioctl_netdevice}.} l'indirizzo locale da esso
2823   utilizzato (nel campo \var{ipi\_spec\_dst}) e l'indirizzo remoto dello
2824   stesso (nel campo \var{ipi\_addr}).
2825
2826 \begin{figure}[!htb]
2827   \footnotesize \centering
2828   \begin{minipage}[c]{15cm}
2829     \includestruct{listati/pktinfo.h}
2830   \end{minipage}
2831   \caption{La struttura \structd{pktinfo} usata dall'opzione
2832     \const{IP\_PKTINFO} per ricavare informazioni sui pacchetti di un socket
2833     di tipo \const{SOCK\_DGRAM}.}
2834   \label{fig:sock_pktinfo_struct}
2835 \end{figure}
2836
2837
2838 L'opzione è utilizzabile solo per socket di tipo \const{SOCK\_DGRAM}. Questa è
2839 una opzione introdotta con i kernel della serie 2.2.x, ed è specifica di
2840 Linux;\footnote{non dovrebbe pertanto essere utilizzata se si ha a cuore la
2841   portabilità.} essa permette di sostituire le opzioni \const{IP\_RECVDSTADDR}
2842 e \const{IP\_RECVIF} presenti in altri Unix (la relativa informazione è quella
2843 ottenibile rispettivamente dai campi \var{ipi\_addr} e \var{ipi\_ifindex} di
2844 \struct{pktinfo}). 
2845
2846 L'opzione prende per \param{optval} un intero usato come valore logico, che
2847 specifica soltanto se insieme al pacchetto deve anche essere inviato o
2848 ricevuto il messaggio \const{IP\_PKTINFO} (vedi
2849 sez.~\ref{sec:net_ancillary_data}); il messaggio stesso dovrà poi essere
2850 letto o scritto direttamente con \func{recvmsg} e \func{sendmsg} (vedi
2851 sez.~\ref{sec:net_sendmsg}).
2852
2853
2854 \item[\const{IP\_RECVTOS}] Quando abilitata l'opzione permette di ricevere
2855   insieme ai pacchetti un messaggio ancillare (vedi
2856   sez.~\ref{sec:net_ancillary_data}) di tipo \const{IP\_TOS}, che contiene un
2857   byte con il valore del campo \textit{Type of Service} dell'intestazione IP
2858   del pacchetto stesso (vedi sez.~\ref{sec:IP_header}).  Prende per
2859   \param{optval} un intero usato come valore logico.
2860
2861 \item[\const{IP\_RECVTTL}] Quando abilitata l'opzione permette di ricevere
2862   insieme ai pacchetti un messaggio ancillare (vedi
2863   sez.~\ref{sec:net_ancillary_data}) di tipo \const{IP\_RECVTTL}, contenente
2864   un byte con il valore del campo \textit{Time to Live} dell'intestazione IP
2865   (vedi sez.~\ref{sec:IP_header}).  L'opzione richiede per \param{optval} un
2866   intero usato come valore logico. L'opzione non è supportata per socket di
2867   tipo \const{SOCK\_STREAM}.
2868
2869 \item[\const{IP\_RECVOPTS}] Quando abilitata l'opzione permette di ricevere
2870   insieme ai pacchetti un messaggio ancillare (vedi
2871   sez.~\ref{sec:net_ancillary_data}) di tipo \const{IP\_OPTIONS}, contenente
2872   le opzioni IP del protocollo (vedi sez.~\ref{sec:IP_options}). Le
2873   intestazioni di instradamento e le altre opzioni sono già riempite con i
2874   dati locali. L'opzione richiede per \param{optval} un intero usato come
2875   valore logico.  L'opzione non è supportata per socket di tipo
2876   \const{SOCK\_STREAM}.
2877
2878 \item[\const{IP\_RETOPTS}] Identica alla precedente \const{IP\_RECVOPTS}, ma
2879   in questo caso restituisce i dati grezzi delle opzioni, senza che siano
2880   riempiti i capi di instradamento e le marche temporali.  L'opzione richiede
2881   per \param{optval} un intero usato come valore logico.  L'opzione non è
2882   supportata per socket di tipo \const{SOCK\_STREAM}.
2883
2884 \item[\const{IP\_TOS}] L'opzione consente di leggere o impostare il campo
2885   \textit{Type of Service} dell'intestazione IP (per una trattazione più
2886   dettagliata, che riporta anche i valori possibili e le relative costanti di
2887   definizione si veda sez.~\ref{sec:IP_header}) che permette di indicare le
2888   priorità dei pacchetti. Se impostato il valore verrà mantenuto per tutti i
2889   pacchetti del socket; alcuni valori (quelli che aumentano la priorità)
2890   richiedono i privilegi di amministrazione con la \itindex{capabilities}
2891   capability \const{CAP\_NET\_ADMIN}.
2892
2893   Il campo TOS è di 8 bit e l'opzione richiede per \param{optval} un intero
2894   che ne contenga il valore. Sono definite anche alcune costanti che
2895   definiscono alcuni valori standardizzati per il \textit{Type of Service},
2896   riportate in tab.~\ref{tab:IP_TOS_values}, il valore di default usato da
2897   Linux è \const{IPTOS\_LOWDELAY}, ma esso può essere modificato con le
2898   funzionalità del cosiddetto \textit{Advanced Routing}. Si ricordi che la
2899   priorità dei pacchetti può essere impostata anche in maniera indipendente
2900   dal protocollo utilizzando l'opzione \const{SO\_PRIORITY} illustrata in
2901   sez.~\ref{sec:sock_generic_options}.
2902
2903 \item[\const{IP\_TTL}] L'opzione consente di leggere o impostare per tutti i
2904   pacchetti associati al socket il campo \textit{Time to Live}
2905   dell'intestazione IP che indica il numero massimo di \textit{hop} (passaggi
2906   da un router ad un altro) restanti al paccheto (per una trattazione più
2907   estesa si veda sez.~\ref{sec:IP_header}).  Il campo TTL è di 8 bit e
2908   l'opzione richiede che \param{optval} sia un intero, che ne conterrà il
2909   valore.
2910
2911 \item[\const{IP\_MINTTL}] L'opzione, introdotta con il kernel 2.6.34, imposta
2912   un valore minimo per il campo \textit{Time to Live} dei pacchetti associati
2913   al socket su cui è attivata, che se non rispettato ne causa lo scarto
2914   automatico. L'opzione è nata per implementare
2915   l'\href{http://www.ietf.org/rfc/rfc5082.txt}{RFC~5082} che la prevede come
2916   forma di protezione per i router che usano il protocollo BGP poiché questi,
2917   essendo in genere adiacenti, possono, impostando un valore di 255, scartare
2918   automaticamente tutti gli eventuali pacchetti falsi creati da un attacco a
2919   questo protocollo, senza doversi curare di verificarne la
2920   validità.\footnote{l'attacco viene in genere portato per causare un
2921     \textit{Denial of Service} aumentando il consumo di CPU del router nella
2922     verifica dell'autenticità di un gran numero di pacchetti di pacchetti
2923     falsi; questi, arrivando da sorgenti diverse da un router adiacente, non
2924     potrebbero più avere un TTL di 255 anche qualora questo fosse stato il
2925     valore di partenza, e l'impostazione dell'opzione consente di scartarli
2926     senza carico aggiuntivo sulla CPU (che altrimenti dovrebbe calcolare una
2927     checksum).}
2928
2929 \item[\const{IP\_HDRINCL}] Se abilitata l'utente deve fornire lui stesso
2930   l'intestazione IP in cima ai propri dati. L'opzione è valida soltanto per
2931   socket di tipo \const{SOCK\_RAW}, e quando utilizzata eventuali valori
2932   impostati con \const{IP\_OPTIONS}, \const{IP\_TOS} o \const{IP\_TTL} sono
2933   ignorati. In ogni caso prima della spedizione alcuni campi
2934   dell'intestazione vengono comunque modificati dal kernel, torneremo
2935   sull'argomento in sez.~\ref{sec:socket_raw}
2936
2937 \item[\const{IP\_RECVERR}] Questa è una opzione introdotta con i kernel della
2938   serie 2.2.x, ed è specifica di Linux. Essa permette di usufruire di un
2939   meccanismo affidabile per ottenere un maggior numero di informazioni in caso
2940   di errori. Se l'opzione è abilitata tutti gli errori generati su un socket
2941   vengono memorizzati su una coda, dalla quale poi possono essere letti con
2942   \func{recvmsg} (vedi sez.~\ref{sec:net_sendmsg}) come messaggi ancillari
2943   (torneremo su questo in sez.~\ref{sec:net_ancillary_data}) di tipo
2944   \const{IP\_RECVERR}.  L'opzione richiede per \param{optval} un intero usato
2945   come valore logico e non è applicabile a socket di tipo
2946   \const{SOCK\_STREAM}.
2947
2948 \itindbeg{Maximum~Transfer~Unit}
2949 \item[\const{IP\_MTU\_DISCOVER}] Questa è una opzione introdotta con i kernel
2950   della serie 2.2.x, ed è specifica di Linux.  L'opzione permette di scrivere
2951   o leggere le impostazioni della modalità usata per la determinazione della
2952   \textit{Path Maximum Transfer Unit} (vedi sez.~\ref{sec:net_lim_dim}) del
2953   socket. L'opzione prende per \param{optval} un valore intero che indica la
2954   modalità usata, da specificare con una delle costanti riportate in
2955   tab.~\ref{tab:sock_ip_mtu_discover}.
2956
2957   \begin{table}[!htb]
2958     \centering
2959     \footnotesize
2960     \begin{tabular}[c]{|l|r|p{7cm}|}
2961       \hline
2962       \multicolumn{2}{|c|}{\textbf{Valore}}&\textbf{Significato} \\
2963       \hline
2964       \hline
2965       \const{IP\_PMTUDISC\_DONT}&0& Non effettua la ricerca dalla \textit{Path
2966                                     MTU}.\\
2967       \const{IP\_PMTUDISC\_WANT}&1& Utilizza il valore impostato per la rotta
2968                                     utilizzata dai pacchetti (dal comando
2969                                     \texttt{route}).\\ 
2970       \const{IP\_PMTUDISC\_DO}  &2& Esegue la procedura di determinazione
2971                                     della \textit{Path MTU} come richiesto
2972                                     dall'\href{http://www.ietf.org/rfc/rfc1191.txt}{RFC~1191}.\\ 
2973       \hline
2974     \end{tabular}
2975     \caption{Valori possibili per l'argomento \param{optval} di
2976       \const{IP\_MTU\_DISCOVER}.} 
2977     \label{tab:sock_ip_mtu_discover}
2978   \end{table}
2979
2980   Il valore di default applicato ai socket di tipo \const{SOCK\_STREAM} è
2981   determinato dal parametro \texttt{ip\_no\_pmtu\_disc} (vedi
2982   sez.~\ref{sec:sock_sysctl}), mentre per tutti gli altri socket di default la
2983   ricerca è disabilitata ed è responsabilità del programma creare pacchetti di
2984   dimensioni appropriate e ritrasmettere eventuali pacchetti persi. Se
2985   l'opzione viene abilitata, il kernel si incaricherà di tenere traccia
2986   automaticamente della \itindex{Maximum~Transfer~Unit} \textit{Path MTU}
2987   verso ciascuna destinazione, e rifiuterà immediatamente la trasmissione di
2988   pacchetti di dimensioni maggiori della MTU con un errore di
2989   \errval{EMSGSIZE}.\footnote{in caso contrario la trasmissione del pacchetto
2990     sarebbe effettuata, ottenendo o un fallimento successivo della
2991     trasmissione, o la frammentazione dello stesso.}
2992
2993 \item[\const{IP\_MTU}] Permette di leggere il valore della \textit{Path MTU}
2994   di percorso del socket.  L'opzione richiede per \param{optval} un intero che
2995   conterrà il valore della \textit{Path MTU} in byte.  Questa è una opzione
2996   introdotta con i kernel della serie 2.2.x, ed è specifica di Linux.
2997
2998   È tramite questa opzione che un programma può leggere, quando si è avuto un
2999   errore di \errval{EMSGSIZE}, il valore della MTU corrente del socket. Si
3000   tenga presente che per poter usare questa opzione, oltre ad avere abilitato
3001   la scoperta della \textit{Path MTU}, occorre che il socket sia stato
3002   esplicitamente connesso con \func{connect}. 
3003
3004   Ad esempio con i socket UDP si potrà ottenere una stima iniziale della
3005   \itindex{Maximum~Transfer~Unit} \textit{Path MTU} eseguendo prima una
3006   \func{connect} verso la destinazione, e poi usando \func{getsockopt} con
3007   questa opzione. Si può anche avviare esplicitamente il procedimento di
3008   scoperta inviando un pacchetto di grosse dimensioni (che verrà scartato) e
3009   ripetendo l'invio coi dati aggiornati. Si tenga infine conto che durante il
3010   procedimento i pacchetti iniziali possono essere perduti, ed è compito
3011   dell'applicazione gestirne una eventuale ritrasmissione.
3012
3013 \itindend{Maximum~Transfer~Unit}
3014
3015 \item[\const{IP\_ROUTER\_ALERT}] Questa è una opzione introdotta con i
3016   kernel della serie 2.2.x, ed è specifica di Linux. Prende per
3017   \param{optval} un intero usato come valore logico. Se abilitata
3018   passa tutti i pacchetti con l'opzione \textit{IP Router Alert} (vedi
3019   sez.~\ref{sec:IP_options}) che devono essere inoltrati al socket
3020   corrente. Può essere usata soltanto per socket di tipo raw.
3021
3022 \itindbeg{multicast}
3023 \item[\const{IP\_MULTICAST\_TTL}] L'opzione permette di impostare o leggere il
3024   valore del campo TTL per i pacchetti \textit{multicast} in uscita associati
3025   al socket. È importante che questo valore sia il più basso possibile, ed il
3026   default è 1, che significa che i pacchetti non potranno uscire dalla rete
3027   locale. Questa opzione consente ai programmi che lo richiedono di superare
3028   questo limite.  L'opzione richiede per
3029   \param{optval} un intero che conterrà il valore del TTL.
3030
3031 \item[\const{IP\_MULTICAST\_LOOP}] L'opzione consente di decidere se i dati
3032   che si inviano su un socket usato con il \textit{multicast} vengano ricevuti
3033   anche sulla stessa macchina da cui li si stanno inviando.  Prende per
3034   \param{optval} un intero usato come valore logico.
3035
3036   In generale se si vuole che eventuali client possano ricevere i dati che si
3037   inviano occorre che questa funzionalità sia abilitata (come avviene di
3038   default). Qualora però non si voglia generare traffico per dati che già sono
3039   disponibili in locale l'uso di questa opzione permette di disabilitare
3040   questo tipo di traffico.
3041
3042 \item[\const{IP\_ADD\_MEMBERSHIP}] L'opzione consente di unirsi ad gruppo di
3043   \textit{multicast}, e può essere usata solo con \func{setsockopt}.
3044   L'argomento \param{optval} in questo caso deve essere una struttura di tipo
3045   \struct{ip\_mreqn}, illustrata in fig.~\ref{fig:ip_mreqn_struct}, che
3046   permette di indicare, con il campo \var{imr\_multiaddr} l'indirizzo del
3047   gruppo di \textit{multicast} a cui ci si vuole unire, con il campo
3048   \var{imr\_address} l'indirizzo dell'interfaccia locale con cui unirsi al
3049   gruppo di \textit{multicast} e con \var{imr\_ifindex} l'indice
3050   dell'interfaccia da utilizzare (un valore nullo indica una interfaccia
3051   qualunque).
3052
3053   Per compatibilità è possibile utilizzare anche un argomento di tipo
3054   \struct{ip\_mreq}, una precedente versione di \struct{ip\_mreqn}, che
3055   differisce da essa soltanto per l'assenza del campo \var{imr\_ifindex}.
3056
3057 \begin{figure}[!htb]
3058   \footnotesize \centering
3059   \begin{minipage}[c]{15cm}
3060     \includestruct{listati/ip_mreqn.h}
3061   \end{minipage}
3062   \caption{La struttura \structd{ip\_mreqn} utilizzata dalle opzioni dei
3063     socket per le operazioni concernenti l'appartenenza ai gruppi di
3064     \textit{multicast}.}
3065   \label{fig:ip_mreqn_struct}
3066 \end{figure}
3067
3068 \item[\const{IP\_DROP\_MEMBERSHIP}] Lascia un gruppo di \textit{multicast},
3069   prende per \param{optval} la stessa struttura \struct{ip\_mreqn} (o
3070   \struct{ip\_mreq}) usata anche per \const{IP\_ADD\_MEMBERSHIP}.
3071
3072 \item[\const{IP\_MULTICAST\_IF}] Imposta l'interfaccia locale per l'utilizzo
3073   del \textit{multicast}, ed utilizza come \param{optval} le stesse strutture
3074   \struct{ip\_mreqn} o \struct{ip\_mreq} delle due precedenti opzioni.
3075
3076 \itindend{multicast}
3077 \end{basedescript}
3078
3079
3080
3081 \subsection{Le opzioni per i protocolli TCP e UDP}
3082 \label{sec:sock_tcp_udp_options}
3083
3084 In questa sezione tratteremo le varie opzioni disponibili per i socket che
3085 usano i due principali protocolli di comunicazione del livello di trasporto;
3086 UDP e TCP.\footnote{come per le precedenti, una descrizione di queste opzioni
3087   è disponibile nella settima sezione delle pagine di manuale, che si può
3088   consultare rispettivamente con \texttt{man 7 tcp} e \texttt{man 7 udp}; le
3089   pagine di manuale però, alla stesura di questa sezione (Agosto 2006) sono
3090   alquanto incomplete.}  Dato che questi due protocolli sono entrambi
3091 trasportati su IP,\footnote{qui si sottintende IPv4, ma le opzioni per TCP e
3092   UDP sono le stesse anche quando si usa IPv6.} oltre alle opzioni generiche
3093 di sez.~\ref{sec:sock_generic_options} saranno comunque disponibili anche le
3094 precedenti opzioni di sez.~\ref{sec:sock_ipv4_options}.\footnote{in realtà in
3095   sez.~\ref{sec:sock_ipv4_options} si sono riportate le opzioni per IPv4, al
3096   solito, qualora si stesse utilizzando IPv6, si potrebbero utilizzare le
3097   opzioni di quest'ultimo.}
3098
3099 Il protocollo che supporta il maggior numero di opzioni è TCP; per poterle
3100 utilizzare occorre specificare \const{SOL\_TCP} (o l'equivalente
3101 \const{IPPROTO\_TCP}) come valore per l'argomento \param{level}. Si sono
3102 riportate le varie opzioni disponibili in tab.~\ref{tab:sock_opt_tcplevel},
3103 dove sono elencate le rispettive costanti da utilizzare come valore per
3104 l'argomento \param{optname}. Dette costanti e tutte le altre costanti e
3105 strutture collegate all'uso delle opzioni TCP sono definite in
3106 \file{netinet/tcp.h}, ed accessibili includendo detto file.\footnote{in realtà
3107   questo è il file usato dalle librerie; la definizione delle opzioni
3108   effettivamente supportate da Linux si trova nel file \texttt{linux/tcp.h},
3109   dal quale si sono estratte le costanti di tab.~\ref{tab:sock_opt_tcplevel}.}
3110
3111 \begin{table}[!htb]
3112   \centering
3113   \footnotesize
3114   \begin{tabular}[c]{|l|c|c|c|l|l|}
3115     \hline
3116     \textbf{Opzione}&\texttt{get}&\texttt{set}&\textbf{flag}&\textbf{Tipo}&
3117                     \textbf{Descrizione}\\
3118     \hline
3119     \hline
3120     \const{TCP\_NODELAY}      &$\bullet$&$\bullet$&$\bullet$&\texttt{int}& 
3121       Spedisce immediatamente i dati in segmenti singoli.\\
3122     \const{TCP\_MAXSEG}       &$\bullet$&$\bullet$&         &\texttt{int}&
3123       Valore della \itindex{Maximum~Segment~Size} MSS per i segmenti in
3124       uscita.\\  
3125     \const{TCP\_CORK}         &$\bullet$&$\bullet$&$\bullet$&\texttt{int}&
3126       Accumula i dati in un unico segmento.\\
3127     \const{TCP\_KEEPIDLE}     &$\bullet$&$\bullet$&         &\texttt{int}& 
3128       Tempo in secondi prima di inviare un \textit{keepalive}.\\
3129     \const{TCP\_KEEPINTVL}    &$\bullet$&$\bullet$&         &\texttt{int}&
3130       Tempo in secondi prima fra \textit{keepalive} successivi.\\
3131     \const{TCP\_KEEPCNT}      &$\bullet$&$\bullet$&         &\texttt{int}& 
3132       Numero massimo di \textit{keepalive} inviati.\\
3133     \const{TCP\_SYNCNT}       &$\bullet$&$\bullet$&         &\texttt{int}& 
3134       Numero massimo di ritrasmissioni di un SYN.\\
3135     \const{TCP\_LINGER2}      &$\bullet$&$\bullet$&         &\texttt{int}&
3136       Tempo di vita in stato \texttt{FIN\_WAIT2}.\\
3137     \const{TCP\_DEFER\_ACCEPT}&$\bullet$&$\bullet$&         &\texttt{int}&
3138       Ritorna da \func{accept} solo in presenza di dati.\\
3139     \const{TCP\_WINDOW\_CLAMP}&$\bullet$&$\bullet$&         &\texttt{int}&
3140       Valore della \itindex{advertised~window} \textit{advertised window}.\\
3141     \const{TCP\_INFO}         &$\bullet$&        &       &\struct{tcp\_info}& 
3142       Restituisce informazioni sul socket.\\
3143     \const{TCP\_QUICKACK}     &$\bullet$&$\bullet$&$\bullet$&\texttt{int}&
3144       Abilita la modalità \textit{quickack}.\\
3145     \const{TCP\_CONGESTION}   &$\bullet$&$\bullet$&         &\texttt{char *}&
3146       Imposta l'algoritmo per il controllo della congestione.\\
3147    \hline
3148   \end{tabular}
3149   \caption{Le opzioni per i socket TCP disponibili al livello
3150     \const{SOL\_TCP}.}
3151   \label{tab:sock_opt_tcplevel}
3152 \end{table}
3153
3154 Le descrizioni delle varie opzioni riportate in
3155 tab.~\ref{tab:sock_opt_tcplevel} sono estremamente sintetiche ed indicative,
3156 la spiegazione del funzionamento delle singole opzioni con una maggiore
3157 quantità di dettagli è fornita nel seguente elenco:
3158 \begin{basedescript}{\desclabelwidth{2.5cm}\desclabelstyle{\nextlinelabel}}
3159
3160
3161 \item[\const{TCP\_NODELAY}] il protocollo TCP utilizza un meccanismo di
3162   bufferizzazione dei dati uscenti, per evitare la trasmissione di tanti
3163   piccoli segmenti con un utilizzo non ottimale della banda
3164   disponibile.\footnote{il problema è chiamato anche \textit{silly window
3165       syndrome}, per averne un'idea si pensi al risultato che si ottiene
3166     quando un programma di terminale invia un segmento TCP per ogni tasto
3167     premuto, 40 byte di intestazione di protocollo con 1 byte di dati
3168     trasmessi; per evitare situazioni del genere è stato introdotto
3169     \index{algoritmo~di~Nagle} l'\textsl{algoritmo di Nagle}.}  Questo
3170   meccanismo è controllato da un apposito algoritmo (detto
3171   \index{algoritmo~di~Nagle} \textsl{algoritmo di Nagle}, vedi
3172   sez.~\ref{sec:tcp_protocol_xxx}).  Il comportamento normale del protocollo
3173   prevede che i dati siano accumulati fintanto che non si raggiunge una
3174   quantità considerata adeguata per eseguire la trasmissione di un singolo
3175   segmento.
3176
3177   Ci sono però delle situazioni in cui questo comportamento può non essere
3178   desiderabile, ad esempio quando si sa in anticipo che l'applicazione invierà
3179   soltanto un piccolo quantitativo di dati;\footnote{è il caso classico di una
3180     richiesta HTTP.} in tal caso l'attesa introdotta dall'algoritmo di
3181   bufferizzazione non soltanto è inutile, ma peggiora le prestazioni
3182   introducendo un ritardo.  Impostando questa opzione si disabilita l'uso
3183   \index{algoritmo~di~Nagle} dell'\textsl{algoritmo di Nagle} ed i dati
3184   vengono inviati immediatamente in singoli segmenti, qualunque sia la loro
3185   dimensione.  Ovviamente l'uso di questa opzione è dedicato a chi ha esigenze
3186   particolari come quella illustrata, che possono essere stabilite solo per la
3187   singola applicazione.
3188
3189   Si tenga conto che questa opzione viene sovrascritta dall'eventuale
3190   impostazione dell'opzione \const{TCP\_CORK} (il cui scopo è sostanzialmente
3191   l'opposto) che blocca l'invio immediato. Tuttavia quando la si abilita viene
3192   sempre forzato lo scaricamento della coda di invio (con conseguente
3193   trasmissione di tutti i dati pendenti), anche qualora si fosse già abilitata
3194   \const{TCP\_CORK}.\footnote{si tenga presente però che \const{TCP\_CORK} può
3195     essere specificata insieme a \const{TCP\_NODELAY} soltanto a partire dal
3196     kernel 2.5.71.}
3197
3198 \item[\const{TCP\_MAXSEG}] con questa opzione si legge o si imposta il valore
3199   della \itindex{Maximum~Segment~Size} MSS (\textit{Maximum~Segment~Size},
3200   vedi sez.~\ref{sec:net_lim_dim} e sez.~\ref{sec:tcp_protocol_xxx}) dei
3201   segmenti TCP uscenti. Se l'opzione è impostata prima di stabilire la
3202   connessione, si cambia anche il valore della \itindex{Maximum~Segment~Size}
3203   MSS annunciata all'altro capo della connessione. Se si specificano valori
3204   maggiori della \itindex{Maximum~Transfer~Unit} MTU questi verranno ignorati,
3205   inoltre TCP imporrà anche i suoi limiti massimo e minimo per questo valore.
3206
3207 \item[\const{TCP\_CORK}] questa opzione è il complemento naturale di
3208   \const{TCP\_NODELAY} e serve a gestire a livello applicativo la situazione
3209   opposta, cioè quella in cui si sa fin dal principio che si dovranno inviare
3210   grosse quantità di dati. Anche in questo caso \index{algoritmo~di~Nagle}
3211   l'\textsl{algoritmo di Nagle} tenderà a suddividerli in dimensioni da lui
3212   ritenute opportune,\footnote{l'algoritmo cerca di tenere conto di queste
3213     situazioni, ma essendo un algoritmo generico tenderà comunque ad
3214     introdurre delle suddivisioni in segmenti diversi, anche quando potrebbero
3215     non essere necessarie, con conseguente spreco di banda.}  ma sapendo fin
3216   dall'inizio quale è la dimensione dei dati si potranno di nuovo ottenere
3217   delle migliori prestazioni disabilitandolo, e gestendo direttamente l'invio
3218   del nostro blocco di dati in soluzione unica.
3219
3220   Quando questa opzione viene abilitata non vengono inviati segmenti di dati
3221   fintanto che essa non venga disabilitata; a quel punto tutti i dati rimasti
3222   in coda saranno inviati in un solo segmento TCP. In sostanza con questa
3223   opzione si può controllare il flusso dei dati mettendo una sorta di
3224   ``\textsl{tappo}'' (da cui il nome in inglese) al flusso di uscita, in modo
3225   ottimizzare a mano l'uso della banda. Si tenga presente che per l'effettivo
3226   funzionamento ci si deve ricordare di disattivare l'opzione al termine
3227   dell'invio del blocco dei dati.
3228
3229   Si usa molto spesso \const{TCP\_CORK} quando si effettua il trasferimento
3230   diretto di un blocco di dati da un file ad un socket con \func{sendfile}
3231   (vedi sez.~\ref{sec:file_sendfile_splice}), per inserire una intestazione
3232   prima della chiamata a questa funzione; senza di essa l'intestazione
3233   potrebbe venire spedita in un segmento a parte, che a seconda delle
3234   condizioni potrebbe richiedere anche una risposta di ACK, portando ad una
3235   notevole penalizzazione delle prestazioni.
3236
3237   Si tenga presente che l'implementazione corrente di \const{TCP\_CORK} non
3238   consente di bloccare l'invio dei dati per più di 200 millisecondi, passati i
3239   quali i dati accumulati in coda sanno inviati comunque.  Questa opzione è
3240   tipica di Linux\footnote{l'opzione è stata introdotta con i kernel della
3241     serie 2.4.x.} e non è disponibile su tutti i kernel unix-like, pertanto
3242   deve essere evitata se si vuole scrivere codice portabile.
3243
3244 \item[\const{TCP\_KEEPIDLE}] con questa opzione si legge o si imposta
3245   l'intervallo di tempo, in secondi, che deve trascorrere senza traffico sul
3246   socket prima che vengano inviati, qualora si sia attivata su di esso
3247   l'opzione \const{SO\_KEEPALIVE}, i messaggi di \textit{keep-alive} (si veda
3248   la trattazione relativa al \textit{keep-alive} in
3249   sez.~\ref{sec:sock_options_main}).  Anche questa opzione non è disponibile
3250   su tutti i kernel unix-like e deve essere evitata se si vuole scrivere
3251   codice portabile.
3252
3253 \item[\const{TCP\_KEEPINTVL}] con questa opzione si legge o si imposta
3254   l'intervallo di tempo, in secondi, fra due messaggi di \textit{keep-alive}
3255   successivi (si veda sempre quanto illustrato in
3256   sez.~\ref{sec:sock_options_main}). Come la precedente non è disponibile su
3257   tutti i kernel unix-like e deve essere evitata se si vuole scrivere codice
3258   portabile.
3259
3260 \item[\const{TCP\_KEEPCNT}] con questa opzione si legge o si imposta il numero
3261   totale di messaggi di \textit{keep-alive} da inviare prima di concludere che
3262   la connessione è caduta per assenza di risposte ad un messaggio di
3263   \textit{keep-alive} (di nuovo vedi sez.~\ref{sec:sock_options_main}). Come
3264   la precedente non è disponibile su tutti i kernel unix-like e deve essere
3265   evitata se si vuole scrivere codice portabile.
3266
3267 \item[\const{TCP\_SYNCNT}] con questa opzione si legge o si imposta il numero
3268   di tentativi di ritrasmissione dei segmenti SYN usati nel
3269   \itindex{three~way~handshake} \textit{three way handshake} prima che il
3270   tentativo di connessione venga abortito (si ricordi quanto accennato in
3271   sez.~\ref{sec:TCP_func_connect}). Sovrascrive per il singolo socket il valore
3272   globale impostato con la \textit{sysctl} \texttt{tcp\_syn\_retries} (vedi
3273   sez.~\ref{sec:sock_ipv4_sysctl}).  Non vengono accettati valori maggiori di
3274   255; anche questa opzione non è standard e deve essere evitata se si vuole
3275   scrivere codice portabile.
3276
3277 \item[\const{TCP\_LINGER2}] con questa opzione si legge o si imposta, in
3278   numero di secondi, il tempo di sussistenza dei socket terminati nello stato
3279   \texttt{FIN\_WAIT2} (si ricordi quanto visto in
3280   sez.~\ref{sec:TCP_conn_term}).\footnote{si tenga ben presente che questa
3281     opzione non ha nulla a che fare con l'opzione \const{SO\_LINGER} che
3282     abbiamo visto in sez.~\ref{sec:sock_options_main}.}  Questa opzione
3283   consente di sovrascrivere per il singolo socket il valore globale impostato
3284   con la \textit{sysctl} \texttt{tcp\_fin\_timeout} (vedi
3285   sez.~\ref{sec:sock_ipv4_sysctl}).  Anche questa opzione è da evitare se si
3286   ha a cuore la portabilità del codice.
3287
3288 \item[\const{TCP\_DEFER\_ACCEPT}] questa opzione consente di modificare il
3289   comportamento standard del protocollo TCP nello stabilirsi di una
3290   connessione; se ricordiamo il meccanismo del \itindex{three~way~handshake}
3291   \textit{three way handshake} illustrato in fig.~\ref{fig:TCP_TWH} possiamo
3292   vedere che in genere un client inizierà ad inviare i dati ad un server solo
3293   dopo l'emissione dell'ultimo segmento di ACK.
3294
3295   Di nuovo esistono situazioni (e la più tipica è quella di una richiesta
3296   HTTP) in cui sarebbe utile inviare immediatamente la richiesta all'interno
3297   del segmento con l'ultimo ACK del \itindex{three~way~handshake}
3298   \textit{three way handshake}; si potrebbe così risparmiare l'invio di un
3299   segmento successivo per la richiesta e il ritardo sul server fra la
3300   ricezione dell'ACK e quello della richiesta.
3301
3302   Se si invoca \const{TCP\_DEFER\_ACCEPT} su un socket dal lato client (cioè
3303   dal lato da cui si invoca \func{connect}) si istruisce il kernel a non
3304   inviare immediatamente l'ACK finale del \itindex{three~way~handshake}
3305   \textit{three way handshake}, attendendo per un po' di tempo la prima
3306   scrittura, in modo da inviare i dati di questa insieme col segmento ACK.
3307   Chiaramente la correttezza di questo comportamento dipende in maniera
3308   diretta dal tipo di applicazione che usa il socket; con HTTP, che invia una
3309   breve richiesta, permette di risparmiare un segmento, con FTP, in cui invece
3310   si attende la ricezione del prompt del server, introduce un inutile ritardo.
3311
3312   Allo stesso tempo il protocollo TCP prevede che sul lato del server la
3313   funzione \func{accept} ritorni dopo la ricezione dell'ACK finale, in tal
3314   caso quello che si fa usualmente è lanciare un nuovo processo per leggere i
3315   successivi dati, che si bloccherà su una \func{read} se questi non sono
3316   disponibili; in questo modo si saranno impiegate delle risorse (per la
3317   creazione del nuovo processo) che non vengono usate immediatamente.  L'uso
3318   di \const{TCP\_DEFER\_ACCEPT} consente di intervenire anche in questa
3319   situazione; quando la si invoca sul lato server (vale a dire su un socket in
3320   ascolto) l'opzione fa sì che \func{accept} ritorni soltanto quando sono
3321   presenti dei dati sul socket, e non alla ricezione dell'ACK conclusivo del
3322   \itindex{three~way~handshake} \textit{three way handshake}.
3323
3324   L'opzione prende un valore intero che indica il numero massimo di secondi
3325   per cui mantenere il ritardo, sia per quanto riguarda il ritorno di
3326   \func{accept} su un server, che per l'invio dell'ACK finale insieme ai dati
3327   su un client. L'opzione è specifica di Linux non deve essere utilizzata in
3328   codice che vuole essere portabile.\footnote{su FreeBSD è presente una
3329     opzione \texttt{SO\_ACCEPTFILTER} che consente di ottenere lo stesso
3330     comportamento di \const{TCP\_DEFER\_ACCEPT} per quanto riguarda il lato
3331     server.}
3332
3333 \item[\const{TCP\_WINDOW\_CLAMP}] con questa opzione si legge o si imposta
3334   alla dimensione specificata, in byte, il valore dichiarato della
3335   \itindex{advertised~window} \textit{advertised window} (vedi
3336   sez.~\ref{sec:tcp_protocol_xxx}). Il kernel impone comunque una dimensione
3337   minima pari a \texttt{SOCK\_MIN\_RCVBUF/2}.  Questa opzione non deve essere
3338   utilizzata in codice che vuole essere portabile.
3339
3340 \begin{figure}[!htb]
3341   \footnotesize \centering
3342   \begin{minipage}[c]{15cm}
3343     \includestruct{listati/tcp_info.h}
3344   \end{minipage}
3345   \caption{La struttura \structd{tcp\_info} contenente le informazioni sul
3346     socket restituita dall'opzione \const{TCP\_INFO}.}
3347   \label{fig:tcp_info_struct}
3348 \end{figure}
3349
3350 \item[\const{TCP\_INFO}] questa opzione, specifica di Linux, ma introdotta
3351   anche in altri kernel (ad esempio FreeBSD) permette di controllare lo stato
3352   interno di un socket TCP direttamente da un programma in user space.
3353   L'opzione restituisce in una speciale struttura \struct{tcp\_info}, la cui
3354   definizione è riportata in fig.~\ref{fig:tcp_info_struct}, tutta una serie
3355   di dati che il kernel mantiene, relativi al socket.  Anche questa opzione
3356   deve essere evitata se si vuole scrivere codice portabile.
3357
3358   Con questa opzione diventa possibile ricevere una serie di informazioni
3359   relative ad un socket TCP così da poter effettuare dei controlli senza dover
3360   passare attraverso delle operazioni di lettura. Ad esempio si può verificare
3361   se un socket è stato chiuso usando una funzione analoga a quella illustrata
3362   in fig.~\ref{fig:is_closing}, in cui si utilizza il valore del campo
3363   \var{tcpi\_state} di \struct{tcp\_info} per controllare lo stato del socket.
3364
3365 \begin{figure}[!htb]
3366   \footnotesize \centering
3367   \begin{minipage}[c]{15cm}
3368     \includecodesample{listati/is_closing.c}
3369   \end{minipage}
3370   \caption{Codice della funzione \texttt{is\_closing.c}, che controlla lo stato
3371     di un socket TCP per verificare se si sta chiudendo.}
3372   \label{fig:is_closing}
3373 \end{figure}
3374
3375 %Si noti come nell'esempio si sia (
3376
3377
3378 \item[\const{TCP\_QUICKACK}] con questa opzione è possibile eseguire una forma
3379   di controllo sull'invio dei segmenti ACK all'interno di in flusso di dati su
3380   TCP. In genere questo invio viene gestito direttamente dal kernel, il
3381   comportamento standard, corrispondente la valore logico di vero (in genere
3382   1) per questa opzione, è quello di inviare immediatamente i segmenti ACK, in
3383   quanto normalmente questo significa che si è ricevuto un blocco di dati e si
3384   può passare all'elaborazione del blocco successivo.
3385
3386   Qualora però la nostra applicazione sappia in anticipo che alla ricezione di
3387   un blocco di dati seguirà immediatamente l'invio di un altro
3388   blocco,\footnote{caso tipico ad esempio delle risposte alle richieste HTTP.}
3389   poter accorpare quest'ultimo al segmento ACK permette di risparmiare sia in
3390   termini di dati inviati che di velocità di risposta. Per far questo si può
3391   utilizzare \const{TCP\_QUICKACK} impostando un valore logico falso (cioè 0),
3392   in questo modo il kernel attenderà così da inviare il prossimo segmento di
3393   ACK insieme ai primi dati disponibili.
3394
3395   Si tenga presente che l'opzione non è permanente, vale a dire che una volta
3396   che la si sia impostata a 0 il kernel la riporterà al valore di default dopo
3397   il suo primo utilizzo. Sul lato server la si può impostare anche una volta
3398   sola su un socket in ascolto, ed essa verrà ereditata da tutti i socket che
3399   si otterranno da esso al ritorno di \func{accept}.
3400
3401 % TODO trattare con gli esempi di apache
3402
3403 \item[\const{TCP\_CONGESTION}] questa opzione permette di impostare quale
3404   algoritmo per il controllo della congestione\footnote{il controllo della
3405     congestione è un meccanismo previsto dal protocollo TCP (vedi
3406     sez.~\ref{sec:tcp_protocol_xxx}) per evitare di trasmettere inutilmente
3407     dati quando una connessione è congestionata; un buon algoritmo è
3408     fondamentale per il funzionamento del protocollo, dato che i pacchetti
3409     persi andrebbero ritrasmessi, per cui inviare un pacchetto su una linea
3410     congestionata potrebbe causare facilmente un peggioramento della
3411     situazione.} utilizzare per il singolo socket. L'opzione è stata
3412   introdotta con il kernel 2.6.13,\footnote{alla data di stesura di queste
3413     note (Set. 2006) è pure scarsamente documentata, tanto che non è neanche
3414     definita nelle intestazioni delle \acr{glibc} per cui occorre definirla a
3415     mano al suo valore che è 13.} e prende come per \param{optval} il
3416   puntatore ad un buffer contenente il nome dell'algoritmo di controllo che
3417   si vuole usare. 
3418
3419   L'uso di un nome anziché di un valore numerico è dovuto al fatto che gli
3420   algoritmi di controllo della congestione sono realizzati attraverso
3421   altrettanti moduli del kernel, e possono pertanto essere attivati a
3422   richiesta; il nome consente di caricare il rispettivo modulo e di introdurre
3423   moduli aggiuntivi che implementino altri meccanismi. 
3424
3425   Per poter disporre di questa funzionalità occorre aver compilato il kernel
3426   attivando l'opzione di configurazione generale
3427   \texttt{TCP\_CONG\_ADVANCED},\footnote{disponibile come \textit{TCP:
3428       advanced congestion control} nel menù \textit{Network->Networking
3429       options}, che a sua volta renderà disponibile un ulteriore menù con gli
3430     algoritmi presenti.} e poi abilitare i singoli moduli voluti con le varie
3431   \texttt{TCP\_CONG\_*} presenti per i vari algoritmi disponibili; un elenco
3432   di quelli attualmente supportati nella versione ufficiale del kernel è
3433   riportato in tab.~\ref{tab:sock_tcp_congestion_algo}.\footnote{la lista è
3434     presa dalla versione 2.6.17.}
3435
3436
3437   Si tenga presente che prima della implementazione modulare alcuni di questi
3438   algoritmi erano disponibili soltanto come caratteristiche generali del
3439   sistema, attivabili per tutti i socket, questo è ancora possibile con la
3440   \textit{sysctl} \texttt{tcp\_congestion\_control} (vedi
3441   sez.~\ref{sec:sock_ipv4_sysctl}) che ha sostituito le precedenti
3442   \textit{sysctl}.\footnote{riportate anche, alla data di stesura di queste
3443     pagine (Set. 2006) nelle pagine di manuale, ma non più presenti.}
3444
3445   \begin{table}[!htb]
3446     \centering
3447     \footnotesize
3448     \begin{tabular}[c]{|l|l|p{10cm}|}
3449       \hline
3450       \textbf{Nome}&\textbf{Configurazione}&\textbf{Riferimento} \\
3451       \hline
3452       \hline
3453       reno& -- &Algoritmo tradizionale, usato in caso di assenza degli altri.\\
3454       \texttt{bic}     &\texttt{TCP\_CONG\_BIC}     & 
3455       \href{http://www.csc.ncsu.edu/faculty/rhee/export/bitcp/index.htm}
3456       {\textsf{http://www.csc.ncsu.edu/faculty/rhee/export/bitcp/index.htm}}.\\
3457       \texttt{cubic}   &\texttt{TCP\_CONG\_CUBIC}     & 
3458       \href{http://www.csc.ncsu.edu/faculty/rhee/export/bitcp/index.htm}
3459       {\textsf{http://www.csc.ncsu.edu/faculty/rhee/export/bitcp/index.htm}}.\\
3460       \texttt{highspeed}&\texttt{TCP\_CONG\_HSTCP}  & 
3461       \href{http://www.icir.org/floyd/hstcp.html}
3462       {\textsf{http://www.icir.org/floyd/hstcp.html}}.\\
3463       \texttt{htcp}    &\texttt{TCP\_CONG\_HTCP}    & 
3464       \href{http://www.hamilton.ie/net/htcp/}
3465       {\textsf{http://www.hamilton.ie/net/htcp/}}.\\
3466       \texttt{hybla}   &\texttt{TCP\_CONG\_HYBLA}   &       
3467       \href{http://www.danielinux.net/projects.html}
3468       {\textsf{http://www.danielinux.net/projects.html}}.\\
3469       \texttt{scalable}&\texttt{TCP\_CONG\_SCALABLE}&  
3470       \href{http://www.deneholme.net/tom/scalable/}
3471       {\textsf{http://www.deneholme.net/tom/scalable/}}.\\
3472       \texttt{vegas}   &\texttt{TCP\_CONG\_VEGAS}   &  
3473       \href{http://www.cs.arizona.edu/protocols/}
3474       {\textsf{http://www.cs.arizona.edu/protocols/}}.\\