Sistemazione ulteriore degli overfull hbox
[gapil.git] / sockctrl.tex
index a1a4a65c0b7e8c645a332ff8e7859e3ec9b2c5e7..07c657eab685eebee01dec1dbf1130b676caef58 100644 (file)
@@ -1,6 +1,6 @@
 %% sockctrl.tex
 %%
-%% Copyright (C) 2004-2017 Simone Piccardi.  Permission is granted to
+%% Copyright (C) 2004-2018 Simone Piccardi.  Permission is granted to
 %% copy, distribute and/or modify this document under the terms of the GNU Free
 %% Documentation License, Version 1.1 or any later version published by the
 %% Free Software Foundation; with the Invariant Sections being "Prefazione",
@@ -822,7 +822,7 @@ come, essendo il campo \var{h\_addr\_list} un puntatore ad strutture di
 indirizzi generiche, questo sia ancora di tipo \texttt{char **} e si possa
 riutilizzare lo stesso puntatore usato per i nomi.
 
-Per ciascun indirizzo valido si provvederà (\texttt{\small 41}) ad una
+Per ciascun indirizzo valido si provvederà (\texttt{\small 41}) a una
 conversione con la funzione \func{inet\_ntop} (vedi
 sez.~\ref{sec:sock_addr_func}) passandole gli opportuni argomenti, questa
 restituirà la stringa da stampare (\texttt{\small 42}) con il valore
@@ -2318,7 +2318,7 @@ tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
   \func{setsockopt} ed utilizza per \param{optval} un puntatore ad una
   struttura \struct{sock\_fprog} (definita in
   \headfile{linux/filter.h}). Questa opzione viene usata principalmente con i
-  socket di tipo \const{PF\_PACKET} (torneremo su questo in
+  socket di tipo \const{AF\_PACKET} (torneremo su questo in
   sez.~\ref{sec:packet_socket}) dalla libreria \texttt{libpcap} per
   implementare programmi di cattura dei pacchetti, e per questo tipo di
   applicazione è opportuno usare sempre quest'ultima.\footnote{la trattazione
@@ -2347,8 +2347,8 @@ tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
   \const{SOCK\_STREAM}.
 
 \item[\constd{SO\_BSDCOMPAT}] questa opzione abilita la compatibilità con il
-  comportamento di BSD (in particolare ne riproduce alcuni bug).  Attualmente è una
-  opzione usata solo per il protocollo UDP e ne è prevista la rimozione.
+  comportamento di BSD (in particolare ne riproduce alcuni bug).  Attualmente
+  è una opzione usata solo per il protocollo UDP e ne è prevista la rimozione.
   L'opzione utilizza per \param{optval} un intero usato come valore logico.
 
   Quando viene abilitata gli errori riportati da messaggi ICMP per un socket
@@ -2529,10 +2529,10 @@ tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
   specificare come argomento per questa opzione sono impostabili tramiti gli
   opportuni valori di \func{sysctl} (vedi sez.~\ref{sec:sock_sysctl}).
 
-  Si tenga presente che nel caso di socket TCP, per entrambe le opzioni
-  \const{SO\_RCVBUF} e \const{SO\_SNDBUF}, il kernel alloca effettivamente una
-  quantità di memoria doppia rispetto a quanto richiesto con
-  \func{setsockopt}. Questo comporta che una successiva lettura con
+  Si tenga presente che nel caso di socket TCP il kernel alloca effettivamente
+  una quantità di memoria doppia rispetto a quanto richiesto con
+  \func{setsockopt} per entrambe le opzioni \const{SO\_RCVBUF} e
+  \const{SO\_SNDBUF}. Questo comporta che una successiva lettura con
   \func{getsockopt} riporterà un valore diverso da quello impostato con
   \func{setsockopt}.  Questo avviene perché TCP necessita dello spazio in più
   per mantenere dati amministrativi e strutture interne, e solo una parte
@@ -2549,8 +2549,8 @@ tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
 
 \item[\constd{SO\_RCVBUFFORCE}] questa opzione, presente dal kernel 2.6.14, è
   identica a \const{SO\_RCVBUF} ma consente ad un processo con i privilegi di
-  amministratore (con la \textit{capability} \const{CAP\_NET\_ADMIN}) di
-  impostare in valore maggiore del limite di
+  amministratore (per la precisione con la \textit{capability}
+  \const{CAP\_NET\_ADMIN}) di impostare in valore maggiore del limite di
   \sysctlrelfile{net/core}{rmem\_max}.
 
 \item[\constd{SO\_RCVLOWAT}] questa opzione imposta il valore che indica il
@@ -2559,13 +2559,14 @@ tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
   segnalando ad una \func{select} (vedi sez.~\ref{sec:TCP_sock_select}) che ci
   sono dati in ingresso. L'opzione utilizza per \param{optval} un intero che
   specifica il numero di byte; con Linux questo valore è sempre 1 e può essere
-  cambiato solo con i kernel a partire dal 2.4. Si tenga presente però che
-  \func{poll} e \func{select} non supportano ancora questa funzionalità e
-  ritornano comunque, indicando il socket come leggibile, non appena almeno un
-  byte è presente mentre in una successiva lettura \func{read} si bloccherà
-  fintanto che non siano disponibili la quantità di byte indicati. Con
-  \func{getsockopt} si può leggere questo valore mentre \func{setsockopt} darà
-  un errore di \errcode{ENOPROTOOPT} quando il cambiamento non è supportato.
+  cambiato solo con i kernel a partire dal 2.4. Si tenga presente però che per
+  i kernel prima del 2.6.28 sia \func{poll} che \func{select} non supportano
+  questa funzionalità e ritornano comunque, indicando il socket come
+  leggibile, non appena almeno un byte è presente, con una successiva lettura
+  con \func{read} che si blocca fintanto che non diventa disponibile la
+  quantità di byte indicati. Con \func{getsockopt} si può leggere questo
+  valore mentre \func{setsockopt} darà un errore di \errcode{ENOPROTOOPT}
+  quando il cambiamento non è supportato.
 
 \item[\constd{SO\_RCVTIMEO}] l'opzione permette di impostare un tempo massimo
   sulle operazioni di lettura da un socket, e prende per \param{optval} una
@@ -2638,8 +2639,8 @@ tab.~\ref{tab:sock_opt_socklevel} sul significato delle varie opzioni:
 
 \item[\constd{SO\_SNDBUFFORCE}] questa opzione, presente dal kernel 2.6.14, è
   identica a \const{SO\_SNDBUF} ma consente ad un processo con i privilegi di
-  amministratore (con la \textit{capability} \const{CAP\_NET\_ADMIN}) di
-  impostare in valore maggiore del limite di
+  amministratore (per la precisione con la \textit{capability}
+  \const{CAP\_NET\_ADMIN}) di impostare in valore maggiore del limite di
   \sysctlrelfile{net/core}{wmem\_max}.
 
 % TODO verificare il timeout con un programma di test
@@ -3097,7 +3098,7 @@ manuale, nel caso specifico la documentazione si può consultare con
 \begin{table}[!htb]
   \centering
   \footnotesize
-  \begin{tabular}[c]{|l|c|c|c|l|p{5.cm}|}
+  \begin{tabular}[c]{|l|c|c|c|l|p{4.8cm}|}
     \hline
     \textbf{Opzione}&\texttt{get}&\texttt{set}&\textbf{flag}&\textbf{Tipo}&
                     \textbf{Descrizione}\\
@@ -3164,7 +3165,7 @@ manuale, nel caso specifico la documentazione si può consultare con
       Ricomincia a ricevere dati di \textit{multicast} per una sorgente.\\
    \hline
   \end{tabular}
-  \caption{Le opzioni disponibili al livello \const{SOL\_IP}.} 
+  \caption{Le opzioni disponibili al livello \const{IPPROTO\_IP}.} 
   \label{tab:sock_opt_iplevel}
 \end{table}
 
@@ -3191,33 +3192,117 @@ seguente elenco:
 
 \begin{figure}[!htb]
   \footnotesize \centering
-  \begin{minipage}[c]{0.70\textwidth}
+  \begin{minipage}[c]{0.90\textwidth}
     \includestruct{listati/ip_mreqn.h}
   \end{minipage}
-  \caption{La struttura \structd{ip\_mreqn} utilizzata dalle opzioni dei
-    socket per le operazioni concernenti l'appartenenza ai gruppi di
+  \caption{La struttura \structd{ip\_mreqn} utilizzata per unirsi a un gruppo di
     \textit{multicast}.}
   \label{fig:ip_mreqn_struct}
 \end{figure}
 
-  Per compatibilità è possibile utilizzare anche un argomento di tipo
-  \struct{ip\_mreq}, una precedente versione di \struct{ip\_mreqn}, che
-  differisce da essa soltanto per l'assenza del campo \var{imr\_ifindex}.
+Questa struttura è presente a partire dal kernel 2.2, per compatibilità è
+possibile utilizzare anche un argomento di tipo \struct{ip\_mreq}, presente
+fino dal kernel 1.2, che differisce da essa soltanto per l'assenza del campo
+\var{imr\_ifindex}; il kernel riconosce il tipo di struttura in base alla
+differente dimensione passata in \param{optlen}. 
+
+\item[\constd{IP\_ADD\_SOURCE\_MEMBERSHIP}] L'opzione consente di unirsi ad
+  gruppo di \textit{multicast}, ricevendo i dati solo da una sorgente
+  specifica; come \const{IP\_ADD\_MEMBERSHIP} può essere usata solo con
+  \func{setsockopt}.
 
+\begin{figure}[!htb]
+  \footnotesize \centering
+  \begin{minipage}[c]{0.90\textwidth}
+    \includestruct{listati/ip_mreq_source.h}
+  \end{minipage}
+  \caption{La struttura \structd{ip\_mreqn} utilizzata per unirsi a un gruppo di
+    \textit{multicast} per una specifica sorgente.}
+  \label{fig:ip_mreq_source_struct}
+\end{figure}
 
-\item[\constd{IP\_BLOCK\_SOURCE}] TODO 
+L'argomento \param{optval} in questo caso è una struttura
+\struct{ip\_mreq\_source} illustrata in fig.~\ref{fig:ip_mreq_source_struct},
+dove il campo \var{imr\_multiaddr} è l'indirizzo del gruppo di
+\textit{multicast}, il campo \var{imr\_interface} l'indirizzo dell'interfaccia
+locale che deve essere usata per aggiungersi al gruppo di \textit{multicast} e
+il campo \var{imr\_sourceaddr} l'indirizzo della sorgente da cui
+l'applicazione vuole ricevere i dati. L'opzione può essere ripetuta più volte
+per collegarsi a diverse sorgenti.
+
+\item[\constd{IP\_BLOCK\_SOURCE}] Questa opzione, disponibile dal kernel
+  2.4.22, consente di smettere di ricevere dati di \textit{multicast} dalla
+  sorgente (e relativo gruppo) specificati dalla struttura
+  \struct{ip\_mreq\_source} (vedi fig.~\ref{fig:ip_mreq_source_struct})
+  passata come argomento \param{optval}. L'opzione è utilizzabile solo se si è
+  già registrati nel gruppo di \textit{multicast} indicato con un precedente
+  utilizzo di \const{IP\_ADD\_MEMBERSHIP} o
+  \const{IP\_ADD\_SOURCE\_MEMBERSHIP}.
 
 \item[\constd{IP\_DROP\_MEMBERSHIP}] Lascia un gruppo di \textit{multicast},
   prende per \param{optval} la stessa struttura \struct{ip\_mreqn} (o
-  \struct{ip\_mreq}) usata anche per \const{IP\_ADD\_MEMBERSHIP}.
+  \struct{ip\_mreq}) usata per \const{IP\_ADD\_MEMBERSHIP} (vedi
+  fig.~\ref{fig:ip_mreqn_struct}).
+
+\item[\constd{IP\_DROP\_SOURCE\_MEMBERSHIP}] Lascia un gruppo di
+  \textit{multicast} per una specifica sorgente, prende per \param{optval} la
+  stessa struttura \struct{ip\_mreq\_source} usata per
+  \const{IP\_ADD\_SOURCE\_MEMBERSHIP} (vedi
+  fig.~\ref{fig:ip_mreq_source_struct}). Se ci si è registrati per più
+  sorgenti nello stesso gruppo, si continuerà a ricevere dati sulle altre. Per
+  smettere di ricevere dati da tutte le sorgenti occorre usare l'opzione
+  \const{IP\_LEAVE\_GROUP}.
+
+\item[\constd{IP\_FREEBIND}] Se abilitata questa opzione, disponibile dal
+  kernel 2.4, consente di usare \func{bind} anche su un indirizzo IP non
+  locale o che ancora non è stato assegnato. Questo permette ad una
+  applicazione di mettersi in ascolto su un socket prima che l'interfaccia
+  sottostante o l'indirizzo che questa deve usare sia stato configurato. È
+  l'equivalente a livello di singolo socket dell'uso della \textit{sysctl}
+  \texttt{ip\_nonlocal\_bind} che vedremo in
+  sez.~\ref{sec:sock_ipv4_sysctl}. Prende per
+  \param{optval} un intero usato come valore logico.
+
+\item[\constd{IP\_HDRINCL}] Se viene abilitata questa opzione, presente dal
+  kernel 2.0, l'utente deve fornire lui stesso l'intestazione del protocollo
+  IP in testa ai propri dati. L'opzione è valida soltanto per socket di tipo
+  \const{SOCK\_RAW}, e quando utilizzata eventuali valori impostati con
+  \const{IP\_OPTIONS}, \const{IP\_TOS} o \const{IP\_TTL} sono ignorati. In
+  ogni caso prima della spedizione alcuni campi dell'intestazione vengono
+  comunque modificati dal kernel, torneremo sull'argomento in
+  sez.~\ref{sec:socket_raw}.  Prende per \param{optval} un intero usato come
+  valore logico.
+
+\item[\constd{IP\_MSFILTER}] L'opzione, introdotta con il kernel 2.4.22,
+  fornisce accesso completo all'interfaccia per il filtraggio delle sorgenti
+  di \textit{multicast} (il cosiddetto \textit{multicast source filtering},
+  definito dall'\href{http://www.ietf.org/rfc/rfc3376.txt}{RFC~3376}).
+
+\begin{figure}[!htb]
+  \footnotesize \centering
+  \begin{minipage}[c]{0.90\textwidth}
+    \includestruct{listati/ip_msfilter.h}
+  \end{minipage}
+  \caption{La struttura \structd{ip\_msfilter} utilizzata per il
+    \textit{multicast source filtering}.}
+  \label{fig:ip_msfilter_struct}
+\end{figure}
 
-\item[\constd{IP\_HDRINCL}] Se abilitata l'utente deve fornire lui stesso
-  l'intestazione IP in cima ai propri dati. L'opzione è valida soltanto per
-  socket di tipo \const{SOCK\_RAW}, e quando utilizzata eventuali valori
-  impostati con \const{IP\_OPTIONS}, \const{IP\_TOS} o \const{IP\_TTL} sono
-  ignorati. In ogni caso prima della spedizione alcuni campi
-  dell'intestazione vengono comunque modificati dal kernel, torneremo
-  sull'argomento in sez.~\ref{sec:socket_raw}
+L'argomento \param{optval} deve essere una struttura di tipo
+\struct{ip\_msfilter} (illustrata in fig.~\ref{fig:ip_msfilter_struct}); il
+campo \var{imsf\_multiaddr} indica l'indirizzo del gruppo di
+\textit{multicast}, il campo \var{imsf\_interface} l'indirizzo
+dell'interfaccia locale, il campo \var{imsf\_mode} indica la modalità di
+filtraggio e con i campi \var{imsf\_numsrc} e \var{imsf\_slist}
+rispettivamente la lunghezza della lista, e la lista stessa, degli indirizzi
+sorgente.
+
+Come ausilio all'uso di questa opzione sono disponibili le macro
+\macro{MCAST\_INCLUDE} e \macro{MCAST\_EXCLUDE} che si possono usare per
+\var{imsf\_mode}. Inoltre si può usare la macro
+\macro{IP\_MSFILTER\_SIZE}\texttt{(\textsf{n})} per determinare il valore
+di \param{optlen} con una struttura \struct{ip\_msfilter} contenente
+\texttt{\textsf{n}} sorgenti in \var{imsf\_slist}.
 
 \item[\constd{IP\_MINTTL}] L'opzione, introdotta con il kernel 2.6.34, imposta
   un valore minimo per il campo \textit{Time to Live} dei pacchetti associati
@@ -3239,9 +3324,9 @@ seguente elenco:
 
 \itindbeg{Path~MTU}
 \item[\constd{IP\_MTU}] Permette di leggere il valore della \textit{Path MTU}
-  di percorso del socket.  L'opzione richiede per \param{optval} un intero che
-  conterrà il valore della \textit{Path MTU} in byte.  Questa è una opzione
-  introdotta con i kernel della serie 2.2.x, ed è specifica di Linux.
+  del socket.  L'opzione richiede per \param{optval} un intero che conterrà il
+  valore della \textit{Path MTU} in byte.  Questa è una opzione introdotta con
+  i kernel della serie 2.2.x, ed è specifica di Linux.
 
   È tramite questa opzione che un programma può leggere, quando si è avuto un
   errore di \errval{EMSGSIZE}, il valore della MTU corrente del socket. Si
@@ -3249,7 +3334,7 @@ seguente elenco:
   la scoperta della \textit{Path MTU}, occorre che il socket sia stato
   esplicitamente connesso con \func{connect}. 
 
-  Ad esempio con i socket UDP si potrà ottenere una stima iniziale della
+  Ad esempio con i socket UDP si p ottenere una stima iniziale della
   \textit{Path MTU} eseguendo prima una \func{connect} verso la destinazione,
   e poi usando \func{getsockopt} con questa opzione. Si può anche avviare
   esplicitamente il procedimento di scoperta inviando un pacchetto di grosse
@@ -3282,6 +3367,7 @@ seguente elenco:
       \constd{IP\_PMTUDISC\_DO}  &2& Esegue la procedura di determinazione
                                      della \textit{Path MTU} come richiesto
                                      dall'\href{http://www.ietf.org/rfc/rfc1191.txt}{RFC~1191}.\\ 
+      \constd{IP\_PMTUDISC\_PROBE}&?& .\\
       \hline
     \end{tabular}
     \caption{Valori possibili per l'argomento \param{optval} di
@@ -4447,10 +4533,11 @@ socket.  Quelli descritti anche nella pagina di manuale, accessibile con
   dati ancillari e di controllo (vedi sez.~\ref{sec:net_ancillary_data}).
 \end{basedescript}
 
-Oltre a questi nella directory \texttt{/proc/sys/net/core} si trovano altri
-file, la cui documentazione dovrebbe essere mantenuta nei sorgenti del kernel,
-nel file \texttt{Documentation/networking/ip-sysctl.txt}; la maggior parte di
-questi però non è documentato:
+Oltre a questi, nella directory \texttt{/proc/sys/net/core} si trovano diversi
+altri file, la cui documentazione, come per gli altri, dovrebbe essere
+mantenuta nei sorgenti del kernel nel file
+\texttt{Documentation/networking/ip-sysctl.txt}; la maggior parte di questi
+però non è documentato:
 \begin{basedescript}{\desclabelwidth{2.2cm}\desclabelstyle{\nextlinelabel}}
 \item[\sysctlrelfiled{net/core}{dev\_weight}] blocco di lavoro (\textit{work
     quantum}) dello \textit{scheduler} di processo dei pacchetti.
@@ -4568,18 +4655,20 @@ di manuale accessibile con \texttt{man 7 ip}, sono i seguenti:
 
 \item[\sysctlrelfiled{net/ipv4}{ipfrag\_high\_thresh}] indica il limite
   massimo (espresso in numero di byte) sui pacchetti IP frammentati presenti
-  in coda; quando questo valore viene raggiunta la coda viene ripulita fino al
+  in coda; quando questo valore viene raggiunto la coda viene ripulita fino al
   valore \texttt{ipfrag\_low\_thresh}. Prende un valore intero.
 
-\item[\sysctlrelfiled{net/ipv4}{ipfrag\_low\_thresh}] soglia bassa
-  (specificata in byte) a cui viene riportata la coda dei pacchetti IP
-  frammentati quando si raggiunge il valore massimo dato da 
+\item[\sysctlrelfiled{net/ipv4}{ipfrag\_low\_thresh}] indica la dimensione
+  (specificata in byte) della soglia inferiore a cui viene riportata la coda
+  dei pacchetti IP frammentati quando si raggiunge il valore massimo dato da
   \texttt{ipfrag\_high\_thresh}. Prende un valore intero.
 
 \item[\sysctlrelfiled{net/ipv4}{ip\_nonlocal\_bind}] se abilitato rende
   possibile ad una applicazione eseguire \func{bind} anche su un indirizzo che
   non è presente su nessuna interfaccia locale. Prende un valore logico e di
-  default è disabilitato.
+  default è disabilitato. La funzionalità può essere abilitata a livello di
+  singolo socket con l'opzione \const{IP\_FREEBIND} illustrata in
+  sez.~\ref{sec:sock_ipv4_options}. 
 
   Questo può risultare utile per applicazioni particolari (come gli
   \textit{sniffer}) che hanno la necessità di ricevere pacchetti anche non
@@ -4951,9 +5040,9 @@ pagina di manuale (accessibile con \texttt{man 7 tcp}), sono i seguenti:
   \item il secondo valore, denominato \textit{default}, indica la dimensione
     di default in byte del buffer di spedizione di un socket TCP.  Questo
     valore sovrascrive il default iniziale impostato per tutti i tipi di
-    socket con \sysctlfile{net/core/wmem\_default}. Il default è 87380 byte,
-    ridotto a 43689 per sistemi con poca memoria. Si può aumentare questo
-    valore quando si desiderano dimensioni più ampie del buffer di
+    socket sul file \sysctlfile{net/core/wmem\_default}. Il default è 87380
+    byte, ridotto a 43689 per sistemi con poca memoria. Si può aumentare
+    questo valore quando si desiderano dimensioni più ampie del buffer di
     trasmissione per i socket TCP, ma come per il precedente
     \sysctlrelfile{net/ipv4}{tcp\_rmem}) se si vuole che in corrispondenza
     aumentino anche le dimensioni usate per la finestra TCP si deve abilitare