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