+\subsection{L'uso di \func{ioctl} per l'accesso ai dispositivi di rete}
+\label{sec:sock_ioctl_netdevice}
+
+Benché non strettamente attinenti alla gestione dei socket, vale la pena di
+trattare qui l'interfaccia di accesso a basso livello ai dispositivi di rete
+che viene appunto fornita attraverso la funzione \texttt{ioctl}. Questa non è
+attinente a caratteristiche specifiche di un qualche protocollo, ma si applica
+a tutti i socket, indipendentemente da tipo e famiglia degli stessi, e
+permette di impostare e rilevare le funzionalità delle interfacce di rete.
+
+\begin{figure}[!htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{\textwidth}
+ \includestruct{listati/ifreq.h}
+ \end{minipage}
+ \caption{La struttura \structd{ifreq} utilizzata dalle \func{ioctl} per le
+ operazioni di controllo sui dispositivi di rete.}
+ \label{fig:netdevice_ifreq_struct}
+\end{figure}
+
+Tutte le operazioni di questo tipo utilizzano come terzo argomento di
+\func{ioctl} il puntatore ad una struttura \struct{ifreq}, la cui definizione
+è illustrata in fig.~\ref{fig:netdevice_ifreq_struct}. Normalmente si utilizza
+il primo campo della struttura, \var{ifr\_name} per specificare il nome
+dell'interfaccia su cui si vuole operare (ad esempio \texttt{eth0},
+\texttt{ppp0}, ecc.), e si inseriscono (o ricevono) i valori relativi alle
+diversa caratteristiche e funzionalità nel secondo campo, che come si può
+notare è definito come una \direct{union} proprio in quanto il suo significato
+varia a secondo dell'operazione scelta.
+
+Si tenga inoltre presente che alcune di queste operazioni (in particolare
+quelle che modificano le caratteristiche dell'interfaccia) sono privilegiate e
+richiedono i privilegi di amministratore o la \itindex{capabilities}
+\textit{capability} \const{CAP\_NET\_ADMIN}, altrimenti si otterrà un errore
+di \errval{EPERM}. Le costanti che identificano le operazioni disponibili
+sono le seguenti:
+\begin{basedescript}{\desclabelwidth{2.7cm}\desclabelstyle{\nextlinelabel}}
+\item[\const{SIOCGIFNAME}] questa è l'unica operazione che usa il campo
+ \var{ifr\_name} per restituire un risultato, tutte le altre lo utilizzano
+ per indicare l'interfaccia sulla quale operare. L'operazione richiede che si
+ indichi nel campo \var{ifr\_ifindex} il valore numerico dell'\textsl{indice}
+ dell'interfaccia, e restituisce il relativo nome in \var{ifr\_name}.
+
+ Il kernel infatti assegna ad ogni interfaccia un numero progressivo, detto
+ appunto \itindex{interface~index} \textit{interface index}, che è quello che
+ effettivamente la identifica nelle operazioni a basso livello, il nome
+ dell'interfaccia è soltanto una etichetta associata a detto \textsl{indice},
+ che permette di rendere più comprensibile l'indicazione dell'interfaccia
+ all'interno dei comandi. Una modalità per ottenere questo valore è usare il
+ comando \cmd{ip link}, che fornisce un elenco delle interfacce presenti
+ ordinato in base a tale valore (riportato come primo campo).
+
+
+\item[\const{SIOCGIFINDEX}] restituisce nel campo \var{ifr\_ifindex} il valore
+ numerico dell'indice dell'interfaccia specificata con \var{ifr\_name}, è in
+ sostanza l'operazione inversa di \const{SIOCGIFNAME}.
+
+\item[\const{SIOCGIFFLAGS}] permette di ottenere nel campo \var{ifr\_flags} il
+ valore corrente dei flag dell'interfaccia specificata (con \var{ifr\_name}).
+ Il valore restituito è una maschera binaria i cui bit sono identificabili
+ attraverso le varie costanti di tab.~\ref{tab:netdevice_iface_flag}.
+
+\begin{table}[htb]
+ \centering
+ \footnotesize
+ \begin{tabular}[c]{|l|p{8cm}|}
+ \hline
+ \textbf{Flag} & \textbf{Significato} \\
+ \hline
+ \hline
+ \const{IFF\_UP} & L'interfaccia è attiva.\\
+ \const{IFF\_BROADCAST} & L'interfaccia ha impostato un indirizzo di
+ \itindex{broadcast} \textit{broadcast} valido.\\
+ \const{IFF\_DEBUG} & È attivo il flag interno di debug.\\
+ \const{IFF\_LOOPBACK} & L'interfaccia è una interfaccia di
+ \textit{loopback}.\\
+ \const{IFF\_POINTOPOINT}&L'interfaccia è associata ad un collegamento
+ \textsl{punto-punto}.\\
+ \const{IFF\_RUNNING} & L'interfaccia ha delle risorse allocate (non può
+ quindi essere disattivata).\\
+ \const{IFF\_NOARP} & L'interfaccia ha il protocollo ARP disabilitato o
+ l'indirizzo del livello di rete non è impostato.\\
+ \const{IFF\_PROMISC} & L'interfaccia è in \index{modo~promiscuo}
+ \textsl{modo promiscuo} (riceve cioè tutti i
+ pacchetti che vede passare, compresi quelli non
+ direttamente indirizzati a lei).\\
+ \const{IFF\_NOTRAILERS}& Evita l'uso di \textit{trailer} nei pacchetti.\\
+ \const{IFF\_ALLMULTI} & Riceve tutti i pacchetti di \itindex{multicast}
+ \textit{multicast}.\\
+ \const{IFF\_MASTER} & L'interfaccia è il master di un bundle per il
+ bilanciamento di carico.\\
+ \const{IFF\_SLAVE} & L'interfaccia è uno slave di un bundle per il
+ bilanciamento di carico.\\
+ \const{IFF\_MULTICAST} & L'interfaccia ha il supporto per il
+ \textit{multicast} \itindex{multicast} attivo.\\
+ \const{IFF\_PORTSEL} & L'interfaccia può impostare i suoi parametri
+ hardware (con l'uso di \struct{ifmap}).\\
+ \const{IFF\_AUTOMEDIA} & L'interfaccia è in grado di selezionare
+ automaticamente il tipo di collegamento.\\
+ \const{IFF\_DYNAMIC} & Gli indirizzi assegnati all'interfaccia vengono
+ persi quando questa viene disattivata.\\
+% \const{IFF\_} & .\\
+ \hline
+ \end{tabular}
+ \caption{Le costanti che identificano i vari bit della maschera binaria
+ \var{ifr\_flags} che esprime i flag di una interfaccia di rete.}
+ \label{tab:netdevice_iface_flag}
+\end{table}
+
+
+\item[\const{SIOCSIFFLAGS}] permette di impostare il valore dei flag
+ dell'interfaccia specificata (sempre con \var{ifr\_name}, non staremo a
+ ripeterlo oltre) attraverso il valore della maschera binaria da passare nel
+ campo \var{ifr\_flags}, che può essere ottenuta con l'OR aritmetico delle
+ costanti di tab.~\ref{tab:netdevice_iface_flag}; questa operazione è
+ privilegiata.
+
+\item[\const{SIOCGIFMETRIC}] permette di leggere il valore della metrica del
+ dispositivo associato all'interfaccia specificata nel campo
+ \var{ifr\_metric}. Attualmente non è implementato, e l'operazione
+ restituisce sempre un valore nullo.
+
+\item[\const{SIOCSIFMETRIC}] permette di impostare il valore della metrica del
+ dispositivo al valore specificato nel campo \var{ifr\_metric}, attualmente
+ non ancora implementato, restituisce un errore di \errval{EOPNOTSUPP}.
+
+\item[\const{SIOCGIFMTU}] permette di leggere il valore della
+ \itindex{Maximum~Transfer~Unit~(MTU)} \textit{Maximum Transfer Unit} del
+ dispositivo nel campo \var{ifr\_mtu}.
+
+\item[\const{SIOCSIFMTU}] permette di impostare il valore della
+ \itindex{Maximum~Transfer~Unit~(MTU)} \textit{Maximum Transfer Unit} del
+ dispositivo al valore specificato campo \var{ifr\_mtu}. L'operazione è
+ privilegiata, e si tenga presente che impostare un valore troppo basso può
+ causare un blocco del kernel.
+
+\item[\const{SIOCGIFHWADDR}] permette di leggere il valore dell'indirizzo
+ hardware del dispositivo associato all'interfaccia nel campo
+ \var{ifr\_hwaddr}; questo viene restituito come struttura \struct{sockaddr}
+ in cui il campo \var{sa\_family} contiene un valore \texttt{ARPHRD\_*}
+ indicante il tipo di indirizzo ed il campo \var{sa\_data} il valore binario
+ dell'indirizzo hardware a partire dal byte 0.
+
+\item[\const{SIOCSIFHWADDR}] permette di impostare il valore dell'indirizzo
+ hardware del dispositivo associato all'interfaccia attraverso il valore
+ della struttura \struct{sockaddr} (con lo stesso formato illustrato per
+ \const{SIOCGIFHWADDR}) passata nel campo \var{ifr\_hwaddr}. L'operazione è
+ privilegiata.
+
+\item[\const{SIOCSIFHWBROADCAST}] imposta l'indirizzo \textit{broadcast}
+ \itindex{broadcast} hardware dell'interfaccia al valore specificato dal
+ campo \var{ifr\_hwaddr}. L'operazione è privilegiata.
+
+\item[\const{SIOCGIFMAP}] legge alcuni parametri hardware (memoria, interrupt,
+ canali di DMA) del driver dell'interfaccia specificata, restituendo i
+ relativi valori nel campo \var{ifr\_map}; quest'ultimo contiene una
+ struttura di tipo \struct{ifmap}, la cui definizione è illustrata in
+ fig.~\ref{fig:netdevice_ifmap_struct}.
+
+\begin{figure}[!htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{\textwidth}
+ \includestruct{listati/ifmap.h}
+ \end{minipage}
+ \caption{La struttura \structd{ifmap} utilizzata per leggere ed impostare i
+ valori dei parametri hardware di un driver di una interfaccia.}
+ \label{fig:netdevice_ifmap_struct}
+\end{figure}
+
+\item[\const{SIOCSIFMAP}] imposta i parametri hardware del driver
+ dell'interfaccia specificata, restituendo i relativi valori nel campo
+ \var{ifr\_map}. Come per \const{SIOCGIFMAP} questo deve essere passato come
+ struttura \struct{ifmap}, secondo la definizione di
+ fig.~\ref{fig:netdevice_ifmap_struct}.
+
+\item[\const{SIOCADDMULTI}] aggiunge un indirizzo di \itindex{multicast}
+ \textit{multicast} ai filtri del livello di collegamento associati
+ dell'interfaccia. Si deve usare un indirizzo hardware da specificare
+ attraverso il campo \var{ifr\_hwaddr}, che conterrà l'opportuna struttura
+ \struct{sockaddr}; l'operazione è privilegiata. Per una modalità alternativa
+ per eseguire la stessa operazione si possono usare i \textit{packet socket},
+ vedi sez.~\ref{sec:packet_socket}.
+
+\item[\const{SIOCDELMULTI}] rimuove un indirizzo di \itindex{multicast}
+ \textit{multicast} ai filtri del livello di collegamento dell'interfaccia,
+ vuole un indirizzo hardware specificato come per \const{SIOCADDMULTI}. Anche
+ questa operazione è privilegiata e può essere eseguita in forma alternativa
+ con i \textit{packet socket}.
+
+\item[\const{SIOCGIFTXQLEN}] permette di leggere la lunghezza della coda di
+ trasmissione del dispositivo associato all'interfaccia specificata nel campo
+ \var{ifr\_qlen}.
+
+\item[\const{SIOCSIFTXQLEN}] permette di impostare il valore della lunghezza
+ della coda di trasmissione del dispositivo associato all'interfaccia, questo
+ deve essere specificato nel campo \var{ifr\_qlen}. L'operazione è
+ privilegiata.
+
+\item[\const{SIOCSIFNAME}] consente di cambiare il nome dell'interfaccia
+ indicata da \var{ifr\_name} utilizzando il nuovo nome specificato nel campo
+ \var{ifr\_rename}.
+
+\end{basedescript}
+
+
+% TODO aggiunta con il kernel 3.14 SIOCGHWTSTAMP per ottenere il timestamp
+% hardware senza modificarlo
+
+Una ulteriore operazione, che consente di ricavare le caratteristiche delle
+interfacce di rete, è \const{SIOCGIFCONF}; però per ragioni di compatibilità
+questa operazione è disponibile soltanto per i socket della famiglia
+\const{AF\_INET} (vale ad dire per socket IPv4). In questo caso l'utente dovrà
+passare come argomento una struttura \struct{ifconf}, definita in
+fig.~\ref{fig:netdevice_ifconf_struct}.
+
+\begin{figure}[!htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{\textwidth}
+ \includestruct{listati/ifconf.h}
+ \end{minipage}
+ \caption{La struttura \structd{ifconf}.}
+ \label{fig:netdevice_ifconf_struct}
+\end{figure}
+
+Per eseguire questa operazione occorrerà allocare preventivamente un buffer di
+contenente un vettore di strutture \struct{ifreq}. La dimensione (in byte) di
+questo buffer deve essere specificata nel campo \var{ifc\_len} di
+\struct{ifconf}, mentre il suo indirizzo andrà specificato nel campo
+\var{ifc\_req}. Qualora il buffer sia stato allocato come una stringa, il suo
+indirizzo potrà essere fornito usando il campo \var{ifc\_buf}.\footnote{si
+ noti che l'indirizzo del buffer è definito in \struct{ifconf} con una
+ \direct{union}, questo consente di utilizzare una delle due forme a piacere.}
+
+La funzione restituisce nel buffer indicato una serie di strutture
+\struct{ifreq} contenenti nel campo \var{ifr\_name} il nome dell'interfaccia e
+nel campo \var{ifr\_addr} il relativo indirizzo IP. Se lo spazio allocato nel
+buffer è sufficiente il kernel scriverà una struttura \struct{ifreq} per
+ciascuna interfaccia attiva, restituendo nel campo \var{ifc\_len} il totale
+dei byte effettivamente scritti. Il valore di ritorno è 0 se l'operazione ha
+avuto successo e negativo in caso contrario.
+
+Si tenga presente che il kernel non scriverà mai sul buffer di uscita dati
+eccedenti numero di byte specificato col valore di \var{ifc\_len} impostato
+alla chiamata della funzione, troncando il risultato se questi non dovessero
+essere sufficienti. Questa condizione non viene segnalata come errore per cui
+occorre controllare il valore di \var{ifc\_len} all'uscita della funzione, e
+verificare che esso sia inferiore a quello di ingresso. In caso contrario si è
+probabilmente\footnote{probabilmente perché si potrebbe essere nella
+ condizione in cui sono stati usati esattamente quel numero di byte.} avuta
+una situazione di troncamento dei dati.
+
+\begin{figure}[!htbp]
+ \footnotesize \centering
+ \begin{minipage}[c]{\codesamplewidth}
+ \includecodesample{listati/iflist.c}
+ \end{minipage}
+ \caption{Il corpo principale del programma \texttt{iflist.c}.}
+ \label{fig:netdevice_iflist}
+\end{figure}
+
+Come esempio dell'uso di queste funzioni si è riportato in
+fig.~\ref{fig:netdevice_iflist} il corpo principale del programma
+\texttt{iflist} in cui si utilizza l'operazione \const{SIOCGIFCONF} per
+ottenere una lista delle interfacce attive e dei relativi indirizzi. Al solito
+il codice completo è fornito nei sorgenti allegati alla guida.
+
+Il programma inizia (\texttt{\small 7--11}) con la creazione del socket
+necessario ad eseguire l'operazione, dopo di che si inizializzano
+opportunamente (\texttt{\small 13--14}) i valori della struttura
+\struct{ifconf} indicando la dimensione del buffer ed il suo
+indirizzo;\footnote{si noti come in questo caso si sia specificato l'indirizzo
+ usando il campo \var{ifc\_buf}, mentre nel seguito del programma si accederà
+ ai valori contenuti nel buffer usando \var{ifc\_req}.} si esegue poi
+l'operazione invocando \func{ioctl}, controllando come sempre la corretta
+esecuzione, ed uscendo in caso di errore (\texttt{\small 15--19}).
+
+Si esegue poi un controllo sulla quantità di dati restituiti segnalando un
+eventuale overflow del buffer (\texttt{\small 21--23}); se invece è tutto a
+posto (\texttt{\small 24--27}) si calcola e si stampa a video il numero di
+interfacce attive trovate. L'ultima parte del programma (\texttt{\small
+ 28--33}) è il ciclo sul contenuto delle varie strutture \struct{ifreq}
+restituite in cui si estrae (\texttt{\small 30}) l'indirizzo ad esse
+assegnato\footnote{si è definito \var{access} come puntatore ad una struttura
+ di tipo \struct{sockaddr\_in} per poter eseguire un \textit{casting}
+ dell'indirizzo del valore restituito nei vari campi \var{ifr\_addr}, così
+ poi da poterlo poi usare come argomento di \func{inet\_ntoa}.} e lo si
+stampa (\texttt{\small 31--32}) insieme al nome dell'interfaccia.
+
+
+
+\subsection{L'uso di \func{ioctl} per i socket TCP e UDP}
+\label{sec:sock_ioctl_IP}
+
+Non esistono operazioni specifiche per i socket IP in quanto tali,\footnote{a
+ parte forse \const{SIOCGIFCONF}, che però resta attinente alle proprietà
+ delle interfacce di rete, per cui l'abbiamo trattata in
+ sez.~\ref{sec:sock_ioctl_netdevice} insieme alle altre che comunque si
+ applicano anche ai socket IP.} mentre per i pacchetti di altri protocolli
+trasportati su IP, qualora li si gestisca attraverso dei socket, si dovrà fare
+riferimento direttamente all'eventuale supporto presente per il tipo di socket
+usato: ad esempio si possono ricevere pacchetti ICMP con socket di tipo
+\texttt{raw}, nel qual caso si dovrà fare riferimento alle operazioni di
+quest'ultimo.
+
+Tuttavia la gran parte dei socket utilizzati nella programmazione di rete
+utilizza proprio il protocollo IP, e quello che succede è che in realtà la
+funzione \func{ioctl} consente di effettuare alcune operazioni specifiche per
+i socket che usano questo protocollo, ma queste vendono eseguite, invece che a
+livello di IP, al successivo livello di trasporto, vale a dire in maniera
+specifica per i socket TCP e UDP.
+
+Le operazioni di controllo disponibili per i socket TCP sono illustrate dalla
+relativa pagina di manuale, accessibile con \texttt{man 7 tcp}, e prevedono
+come possibile valore per il secondo argomento della funzione le costanti
+illustrate nell'elenco seguente; il terzo argomento della funzione, gestito
+come \itindex{value~result~argument} \textit{value result argument}, deve
+essere sempre il puntatore ad una variabile di tipo \ctyp{int}:
+\begin{basedescript}{\desclabelwidth{2.5cm}\desclabelstyle{\nextlinelabel}}
+\item[\const{SIOCINQ}] restituisce la quantità di dati non ancora letti
+ presenti nel buffer di ricezione; il socket non deve essere in stato
+ \texttt{LISTEN}, altrimenti si avrà un errore di \errval{EINVAL}.
+\item[\const{SIOCATMARK}] ritorna un intero non nullo, da intendere come
+ valore logico, se il flusso di dati letti sul socket è arrivato sulla
+ posizione (detta anche \textit{urgent mark}) in cui sono stati ricevuti
+ \itindex{out-of-band} dati urgenti (vedi sez.~\ref{sec:TCP_urgent_data}).
+ Una operazione di lettura da un socket non attraversa mai questa posizione,
+ per cui è possibile controllare se la si è raggiunta o meno con questa
+ operazione.
+
+ Questo è utile quando si attiva l'opzione \const{SO\_OOBINLINE} (vedi
+ sez.~\ref{sec:sock_generic_options}) per ricevere i dati urgenti all'interno
+ del flusso dei dati ordinari del socket;\footnote{vedremo in
+ sez.~\ref{sec:TCP_urgent_data} che in genere i dati urgenti presenti su un
+ socket si leggono \textit{out-of-band} usando un opportuno flag per
+ \func{recvmsg}.} in tal caso quando \const{SIOCATMARK} restituisce un
+ valore non nullo si saprà che la successiva lettura dal socket restituirà i
+ dati urgenti e non il normale traffico; torneremo su questo in maggior
+ dettaglio in sez.~\ref{sec:TCP_urgent_data}.
+
+\item[\const{SIOCOUTQ}] restituisce la quantità di dati non ancora inviati
+ presenti nel buffer di spedizione; come per \const{SIOCINQ} il socket non
+ deve essere in stato \texttt{LISTEN}, altrimenti si avrà un errore di
+ \errval{EINVAL}.
+\end{basedescript}
+
+Le operazioni di controllo disponibili per i socket UDP, anch'esse illustrate
+dalla relativa pagina di manuale accessibile con \texttt{man 7 udp}, sono
+quelle indicate dalle costanti del seguente elenco; come per i socket TCP il
+terzo argomento viene gestito come \itindex{value~result~argument}
+\textit{value result argument} e deve essere un puntatore ad una variabile di
+tipo \ctyp{int}:
+\begin{basedescript}{\desclabelwidth{2.5cm}\desclabelstyle{\nextlinelabel}}
+\item[\const{FIONREAD}] restituisce la dimensione in byte del primo pacchetto
+ in attesa di ricezione, o 0 qualora non ci sia nessun pacchetto.
+\item[\const{TIOCOUTQ}] restituisce il numero di byte presenti nella coda di
+ invio locale; questa opzione è supportata soltanto a partire dal kernel 2.4