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