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