+ \begin{errlist}
+ \item[\errcode{EBADF}] l'argomento \param{sockfd} non è un file descriptor
+ valido.
+ \item[\errcode{ENOTSOCK}] l'argomento \param{sockfd} non è un socket.
+ \item[\errcode{EOPNOTSUPP}] il socket è di un tipo che non supporta questa
+ operazione.
+ \item[\errcode{EAGAIN} o \errcode{EWOULDBLOCK}] il socket è stato impostato
+ come non bloccante (vedi \secref{sec:file_noblocking}), e non ci sono
+ connessioni in attesa di essere accettate.
+ \item[\errcode{EPERM}] Le regole del firewall non consentono la connessione.
+ \item[\errcode{ENOBUFS}, \errcode{ENOMEM}] questo spesso significa che
+ l'allocazione della memoria è limitata dai limiti sui buffer dei socket,
+ non dalla memoria di sistema.
+ \item[\errcode{EINTR}] La funzione è stata interrotta da un segnale.
+ \end{errlist}
+ Inoltre possono essere restituiti gli errori di rete relativi al nuovo
+ socket, diversi a secondo del protocollo, come: \errval{EMFILE},
+ \errval{EINVAL}, \errval{ENOSR}, \errval{ENOBUFS}, \errval{EFAULT},
+ \errval{EPERM}, \errval{ECONNABORTED}, \errval{ESOCKTNOSUPPORT},
+ \errval{EPROTONOSUPPORT}, \errval{ETIMEDOUT}, \errval{ERESTARTSYS}.}
+\end{prototype}
+
+La funzione estrae la prima connessione relativa al socket \param{sockfd} in
+attesa sulla coda delle connessioni complete, che associa ad nuovo socket con
+le stesse caratteristiche di \param{sockfd}. Il socket originale non viene
+toccato e resta nello stato di \texttt{LISTEN}, mentre il nuovo socket viene
+posto nello stato \texttt{ESTABLISHED}. Nella struttura \param{addr} e nella
+variabile \param{addrlen} vengono restituiti indirizzo e relativa lunghezza
+del client che si è connesso.
+
+I due argomenti \param{addr} e \param{addrlen} (si noti che quest'ultimo è
+passato per indirizzo per avere indietro il valore) sono usati per ottenere
+l'indirizzo del client da cui proviene la connessione. Prima della chiamata
+\param{addrlen} deve essere inizializzato alle dimensioni della struttura il
+cui indirizzo è passato come argomento in \param{addr}; al ritorno della
+funzione \param{addrlen} conterrà il numero di byte scritti dentro
+\param{addr}. Se questa informazione non interessa basterà inizializzare a
+\val{NULL} detti puntatori.
+
+Se la funzione ha successo restituisce il descrittore di un nuovo socket
+creato dal kernel (detto \textit{connected socket}) a cui viene associata la
+prima connessione completa (estratta dalla relativa coda, vedi
+\secref{sec:TCP_func_listen}) che il client ha effettuato verso il socket
+\param{sockfd}. Quest'ultimo (detto \textit{listening socket}) è quello creato
+all'inizio e messo in ascolto con \func{listen}, e non viene toccato dalla
+funzione. Se non ci sono connessioni pendenti da accettare la funzione mette
+in attesa il processo\footnote{a meno che non si sia impostato il socket per
+ essere non bloccante (vedi \secref{sec:file_noblocking}), nel qual caso
+ ritorna con l'errore \errcode{EAGAIN}. Torneremo su questa modalità di
+ operazione in \secref{sec:xxx_sock_noblock}.} fintanto che non ne arriva
+una.
+
+La funzione può essere usata solo con socket che supportino la connessione
+(cioè di tipo \const{SOCK\_STREAM}, \const{SOCK\_SEQPACKET} o
+\const{SOCK\_RDM}). Per alcuni protocolli che richiedono una conferma
+esplicita della connessione,\footnote{attualmente in Linux solo DECnet ha
+ questo comportamento.} la funzione opera solo l'estrazione dalla coda delle
+connessioni, la conferma della connessione viene eseguita implicitamente dalla
+prima chiamata ad una \func{read} o una \func{write}, mentre il rifiuto della
+connessione viene eseguito con la funzione \func{close}.
+
+È da chiarire che Linux presenta un comportamento diverso nella gestione degli
+errori rispetto ad altre implementazioni dei socket BSD, infatti la funzione
+\func{accept} passa gli errori di rete pendenti sul nuovo socket come codici
+di errore per \func{accept}, per cui l'applicazione deve tenerne conto ed
+eventualmente ripetere la chiamata alla funzione come per l'errore di
+\errcode{EAGAIN}. Un'altra differenza con BSD è che la funzione non fa
+ereditare al nuovo socket i flag del socket originale, come
+\const{O\_NONBLOCK},\footnote{ed in generale tutti quelli che si possono
+ impostare con \func{fcntl}, vedi \secref{sec:file_fcntl}.} che devono essere
+rispecificati ogni volta. Tutto questo deve essere tenuto in conto se si
+devono scrivere programmi portabili.
+
+Il meccanismo di funzionamento di \func{accept} è essenziale per capire il
+funzionamento di un server: in generale infatti c'è sempre un solo socket in
+ascolto, che resta per tutto il tempo nello stato \texttt{LISTEN}, mentre le
+connessioni vengono gestite dai nuovi socket ritornati da \func{accept}, che
+si trovano automaticamente nello stato \texttt{ESTABLISHED}, e vengono
+utilizzati fino alla chiusura della connessione, che avviene su di essi. Si
+può riconoscere questo schema anche nell'esempio elementare in
+\figref{fig:TCP_serv_code} dove per ogni connessione il socket creato da
+\func{accept} viene chiuso dopo l'invio dei dati.
+
+
+\subsection{La funzione \func{close}}
+\label{sec:TCP_func_close}
+
+La funzione standard Unix \func{close} (vedi \secref{sec:file_close}) che si
+usa sui file può essere usata con lo stesso effetto anche sui file descriptor
+associati ad un socket.
+
+L'azione di questa funzione quando applicata a socket è di marcarlo come
+chiuso e ritornare immediatamente al processo. Una volta chiamata il socket
+descriptor non è più utilizzabile dal processo e non può essere usato come
+argomento per una \func{write} o una \func{read} (anche se l'altro capo della
+connessione non avesse chiuso la sua parte). Il kernel invierà comunque tutti
+i dati che ha in coda prima di iniziare la sequenza di chiusura.
+
+Vedremo più avanti in \secref{sec:TCP_so_linger} come è possibile cambiare
+questo comportamento, e cosa deve essere fatto perché il processo possa
+assicurarsi che l'altro capo abbia ricevuto tutti i dati.
+
+Come per tutti i file descriptor anche per i socket viene mantenuto un numero
+di riferimenti, per cui se più di un processo ha lo stesso socket aperto
+l'emissione del FIN e la sequenza di chiusura di TCP non viene innescata
+fintanto che il numero di riferimenti non si annulla, questo si applica, come
+visto in \secref{sec:file_sharing}, sia ai file descriptor duplicati che a
+quelli ereditati dagli eventuali processi figli, ed è il comportamento che ci
+si aspetta in una qualunque applicazione client/server.
+
+Per attivare immediatamente l'emissione del FIN e la sequenza di chiusura
+descritta in \secref{sec:TCP_conn_term}, si può invece usare la funzione
+\func{shutdown} su cui torneremo in seguito (vedi \secref{sec:xxx_shutdown}).
+
+
+
+\section{Un esempio di applicazione}
+\label{sec:TCP_application}
+
+Avendo introdotto le funzioni di base per la gestione dei socket, potremo
+vedere in questa sezione un esempio di applicazione elementare. Prima di
+passare agli esempi del client e del server, inizieremo riprendendo con
+maggiori dettagli una caratteristica delle funzioni di I/O, già accennata in
+\secref{sec:file_read} e \secref{sec:file_write}, che nel caso dei socket è
+particolarmente rilevante, per poi passare agli esempi, sia di server
+iterativo, che di server concorrente.
+
+
+\subsection{Il comportamento delle funzioni di I/O}
+\label{sec:sock_io_behav}
+
+Una cosa che si tende a dimenticare quando si ha a che fare con i socket è che
+le funzioni di input/output non sempre hanno lo stesso comportamento che
+avrebbero con i normali file di dati (in particolare questo accade per i
+socket di tipo stream).
+
+Infatti con i socket è comune che funzioni come \func{read} o \func{write}
+possano restituire in input o scrivere in output un numero di byte minore di
+quello richiesto. Come già accennato in \secref{sec:file_read} questo è un
+comportamento normale per l'I/O su file, ma con i normali file di dati il
+problema si avverte solo quando si incontra la fine del file, in generale non
+è così, e con i socket questo è particolarmente evidente.
+
+Quando ci si trova ad affrontare questo comportamento tutto quello che si deve
+fare è semplicemente ripetere la lettura (o la scrittura) per la quantità di
+byte restanti, tenendo conto che le funzioni si possono bloccare se i dati non
+sono disponibili: è lo stesso comportamento che si può avere scrivendo più di
+\const{PIPE\_BUF} byte in una pipe (si riveda quanto detto in
+\secref{sec:ipc_pipes}).
+
+\begin{figure}[htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{15cm}
+ \includecodesample{listati/FullRead.c}
+ \end{minipage}
+ \normalsize
+ \caption{La funzione \func{FullRead}, che legge esattamente \var{count} byte
+ da un file descriptor, iterando opportunamente le letture.}
+ \label{fig:sock_FullRead_code}
+\end{figure}
+
+Per questo motivo, seguendo l'esempio di R. W. Stevens in \cite{UNP1}, si sono
+definite due funzioni, \func{FullRead} e \func{FullWrite}, che eseguono
+lettura e scrittura tenendo conto di questa caratteristica, ed in grado di
+ritornare dopo avere letto o scritto esattamente il numero di byte
+specificato; il sorgente è riportato rispettivamente in
+\figref{fig:sock_FullRead_code} e \figref{fig:sock_FullWrite_code} ed è
+disponibile fra i sorgenti allegati alla guida nei file \file{FullRead.c} e
+\file{FullWrite.c}.
+
+\begin{figure}[htb]
+ \centering
+ \footnotesize \centering
+ \begin{minipage}[c]{15cm}
+ \includecodesample{listati/FullWrite.c}
+ \end{minipage}
+ \normalsize
+ \caption{La funzione \func{FullWrite}, che scrive esattamente \var{count}
+ byte su un file descriptor, iterando opportunamente le scritture.}
+ \label{fig:sock_FullWrite_code}
+\end{figure}
+
+Come si può notare le due funzioni ripetono la lettura/scrittura in un ciclo
+fino all'esaurimento del numero di byte richiesti, in caso di errore viene
+controllato se questo è \errcode{EINTR} (cioè un'interruzione della system
+call dovuta ad un segnale), nel qual caso l'accesso viene ripetuto, altrimenti
+l'errore viene ritornato al programma chiamante, interrompendo il ciclo.
+
+Nel caso della lettura, se il numero di byte letti è zero, significa che si è
+arrivati alla fine del file (per i socket questo significa in genere che
+l'altro capo è stato chiuso, e non è quindi più possibile leggere niente) e
+pertanto si ritorna senza aver concluso la lettura di tutti i byte richiesti.
+
+
+\subsection{Un primo esempio di client}
+\label{sec:TCP_cli_sample}
+
+Il primo esempio di applicazione delle funzioni viste finora (sia in
+\capref{cha:socket_intro} che in \secref{sec:TCP_functions}) è relativo alla
+creazione di un client elementare per il servizio \textit{daytime}, un
+servizio standard che restituisce l'ora locale della macchina a cui si
+effettua la richiesta, e che è assegnato alla porta 13.
+
+In \figref{fig:TCP_cli_code} è riportata la sezione principale del codice del
+nostro client. Il sorgente completo del programma
+(\file{ElemDaytimeTCPClient.c}, che comprende il trattamento delle opzioni e
+una funzione per stampare un messaggio di aiuto) è allegato alla guida nella
+sezione dei codici sorgente e può essere compilato su una qualunque macchina
+GNU/Linux.
+
+\begin{figure}[!htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{15cm}
+ \includecodesample{listati/ElemDaytimeTCPClient.c}
+ \end{minipage}
+ \normalsize
+ \caption{Esempio di codice di un client elementare per il servizio daytime.}
+ \label{fig:TCP_cli_code}
+\end{figure}
+
+Il programma anzitutto (\texttt{\small 1--5}) include gli header necessari;
+dopo la dichiarazione delle variabili (\texttt{\small 9--12}) si è omessa
+tutta la parte relativa al trattamento degli argomenti passati dalla linea di
+comando (effettuata con le apposite funzioni illustrate in
+\capref{sec:proc_opt_handling}).
+
+Il primo passo (\texttt{\small 14--18}) è creare un \textit{socket} TCP
+(quindi di famiglia \const{AF\_INET} e di tipo \const{SOCK\_STREAM}). La
+funzione \func{socket} ritorna il descrittore che viene usato per identificare
+il socket in tutte le chiamate successive. Nel caso la chiamata fallisca si
+stampa un errore (\texttt{\small 16}) con la funzione \func{perror} e si esce
+(\texttt{\small 16}) con un codice di errore.
+
+Il passo seguente (\texttt{\small 19--27}) è quello di costruire un'apposita
+struttura \struct{sockaddr\_in} in cui sarà inserito l'indirizzo del server ed
+il numero della porta del servizio. Il primo passo (\texttt{\small 20}) è
+inizializzare tutto a zero, per poi inserire il tipo di protocollo
+(\texttt{\small 21}) e la porta (\texttt{\small 22}), usando per quest'ultima
+la funzione \func{htons} per convertire il formato dell'intero usato dal
+computer a quello usato nella rete, infine \texttt{\small 23--27} si può
+utilizzare la funzione \func{inet\_pton} per convertire l'indirizzo numerico
+passato dalla linea di comando.
+
+A questo punto (\texttt{\small 28--32}) usando la funzione \func{connect} sul
+socket creato in precedenza (\texttt{\small 29}) si può stabilire la
+connessione con il server. Per questo si deve utilizzare come secondo
+argomento la struttura preparata in precedenza con il relativo indirizzo; si
+noti come, esistendo diversi tipi di socket, si sia dovuto effettuare un cast.
+Un valore di ritorno della funzione negativo implica il fallimento della
+connessione, nel qual caso si stampa un errore (\texttt{\small 30}) e si
+ritorna (\texttt{\small 31}).
+
+Completata con successo la connessione il passo successivo (\texttt{\small
+ 34--40}) è leggere la data dal socket; il protocollo prevede che il server
+invii sempre una stringa alfanumerica di 26 caratteri, nella forma giorno
+della settimana, mese, ora minuto e secondo, anno, seguita dai caratteri di
+teminazione \verb|\r\n|, cioè qualcosa del tipo:
+\begin{verbatim}
+Wed Apr 4 00:53:00 2001\r\n
+\end{verbatim}
+questa viene letta dal socket (\texttt{\small 34}) con la funzione \func{read}
+in un buffer temporaneo; la stringa poi deve essere terminata (\texttt{\small
+ 35}) con il solito carattere nullo per poter essere stampata (\texttt{\small
+ 36}) sullo standard output con l'uso di \func{fputs}.
+
+Come si è già spiegato in \secref{sec:sock_io_behav} la risposta dal socket
+potrà arrivare in un unico pacchetto di 26 byte (come avverrà senz'altro nel
+caso in questione) ma potrebbe anche arrivare in 26 pacchetti di un byte. Per
+questo nel caso generale non si può mai assumere che tutti i dati arrivino con
+una singola lettura, pertanto quest'ultima deve essere effettuata in un ciclo
+in cui si continui a leggere fintanto che la funzione \func{read} non ritorni
+uno zero (che significa che l'altro capo ha chiuso la connessione) o un numero
+minore di zero (che significa un errore nella connessione).
+
+Si noti come in questo caso la fine dei dati sia specificata dal server che
+chiude la connessione (anche questo è quanto richiesto dal protocollo); questa
+è una delle tecniche possibili (è quella usata pure dal protocollo HTTP), ma
+ce ne possono essere altre, ad esempio FTP marca la conclusione di un blocco
+di dati con la sequenza ASCII \verb|\r\n| (carriage return e line feed),
+mentre il DNS mette la lunghezza in testa ad ogni blocco che trasmette. Il
+punto essenziale è che TCP non provvede nessuna indicazione che permetta di
+marcare dei blocchi di dati, per cui se questo è necessario deve provvedere il
+programma stesso.
+
+Se abilitiamo il servizio \textit{daytime}\footnote{in genere questo viene
+ fornito direttamente dal \textsl{superdemone} \texttt{inetd}, pertanto basta
+ assicurarsi che esso sia abilitato nel relativo file di configurazione.}
+possiamo verificare il funzionamento del nostro client, avremo allora:
+\begin{verbatim}
+[piccardi@gont sources]$ ./daytime 127.0.0.1
+Mon Apr 21 20:46:11 2003
+\end{verbatim}%$
+e come si vede tutto funziona regolarmente.
+
+
+\subsection{Un primo esempio di server}
+\label{sec:TCP_serv_sample}
+
+Dopo aver illustrato il client daremo anche un esempio di un server
+elementare, che sia anche in grado di rispondere al precedente client. Come
+primo esempio realizzeremo un server iterativo, in grado di fornire una sola
+risposta alla volta. Il codice del programma è nuovamente mostrato in
+\figref{fig:TCP_serv_code}, il sorgente completo
+(\file{ElemDaytimeTCPServer.c}) è allegato insieme agli altri file degli
+esempi.
+
+\begin{figure}[!htbp]
+ \footnotesize \centering
+ \begin{minipage}[c]{15cm}
+ \includecodesample{listati/ElemDaytimeTCPServer.c}
+ \end{minipage}
+ \normalsize
+ \caption{Esempio di codice di un semplice server per il servizio daytime.}
+ \label{fig:TCP_serv_code}
+\end{figure}
+
+Come per il client si includono (\texttt{\small 1--9}) gli header necessari a
+cui è aggiunto quello per trattare i tempi, e si definiscono (\texttt{\small
+ 14--18}) alcune costanti e le variabili necessarie in seguito, come nel caso
+precedente si sono omesse le parti relative al trattamento delle opzioni da
+riga di comando.
+
+La creazione del socket (\texttt{\small 20--24}) è analoga al caso precedente,
+come pure l'inizializzazione (\texttt{\small 25--29}) della struttura
+\struct{sockaddr\_in}, anche in questo caso (\texttt{\small 28}) si usa la
+porta standard del servizio daytime, ma come indirizzo IP si usa
+(\texttt{\small 27}) il valore predefinito \const{INET\_ANY}, che corrisponde
+ad un indirizzo generico.
+
+Si effettua poi (\texttt{\small 30--34}) la chiamata alla funzione \func{bind}
+che permette di associare la precedente struttura al socket, in modo che
+quest'ultimo possa essere usato per accettare connessioni su una qualunque
+delle interfacce di rete locali. In caso di errore si stampa (\texttt{\small
+ 31}) un messaggio, e si termina (\texttt{\small 32}) immediatamente il
+programma.
+
+Il passo successivo (\texttt{\small 35--39}) è quello di mettere ``in
+ascolto'' il socket; questo viene fatto (\texttt{\small 36}) con la funzione
+\func{listen} che dice al kernel di accettare connessioni per il socket che
+abbiamo creatp; la funzione indica inoltre, con il secondo parametro, il
+numero massimo di connessioni che il kernel accetterà di mettere in coda per
+il suddetto socket. Di nuovo in caso di errore si stampa (\texttt{\small 37})
+un messaggio, e si esce (\texttt{\small 38}) immediatamente.
+
+La chiamata a \func{listen} completa la preparazione del socket per l'ascolto
+(che viene chiamato anche \textit{listening descriptor}) a questo punto si può
+procedere con il ciclo (\texttt{\small 40--53}) principale che viene eseguito
+indefinitamente. Il primo passo è porsi (\texttt{\small 42}) in attesa di
+connessioni con la chiamata alla funzione \func{accept}, come in precedenza in
+caso di errore si stampa (\texttt{\small 43}) un messaggio, e si esce
+(\texttt{\small 44}).
+
+Il provesso resterà in stato di \textit{sleep} fin quando non arriva e viene
+accettata una connessione da un client; quando questo avviene \func{accept}
+ritorna un secondo descrittore di socket, che viene chiamato \textit{connected
+ descriptor}, e che è quello che verrà usato dalla successiva chiamata alla
+\func{write} per scrivere la risposta al client.
+
+Il ciclo quindi proseguirà determinando (\texttt{\small 46}) il tempo corrente
+con una chiamata a \texttt{time}, con il quale si potrà opportunamente
+costruire (\texttt{\small 47}) la stringa con la data da trasmettere
+(\texttt{\small 48}) con la chiamata a \func{write}. Completata la
+trasmissione il nuovo socket viene chiuso (\texttt{\small 52}). A questo
+punto il ciclo si chiude ricominciando da capo in modo da poter ripetere
+l'invio della data in risposta ad una successiva connessione.
+
+È importante notare che questo server è estremamente elementare, infatti a
+parte il fatto di poter essere usato solo con indirizzi IPv4, esso è in grado
+di rispondere ad un solo un client alla volta: è cioè, come dicevamo, un
+\textsl{server iterativo}. Inoltre esso è scritto per essere lanciato da linea
+di comando, se lo si volesse utilizzare come demone occorrerebbero le
+opportune modifiche\footnote{come una chiamata a \func{daemon} prima
+ dell'inizio del ciclo principale.} per tener conto di quanto illustrato in
+\secref{sec:sess_daemon}. Si noti anche che non si è inserita nessuna forma di
+gestione della terminazione del processo, dato che tutti i file descriptor
+vengono chiusi automaticamente alla sua uscita, e che, non generando figli,
+non è necessario preoccuparsi di gestire la loro terminazione.
+
+
+\subsection{Un esempio di server \textit{daytime} concorrente}
+\label{sec:TCP_cunc_daytime}
+
+Il server \texttt{daytime} dell'esempio in \secref{sec:TCP_cli_sample} è un
+tipico esempio di server iterativo, in cui viene servita una richiesta alla
+volta; in generale però, specie se il servizio è più complesso e comporta uno
+scambio di dati più sostanzioso di quello in questione, non è opportuno
+bloccare un server nel servizio di un client per volta; per questo si ricorre
+alle capacità di multitasking del sistema.
+
+Come già visto per i server basati sui meccanismi di intercomunicazione locale
+visti in \capref{cha:IPC}, il modo più immediato per creare un server
+concorrente è quello di usare la funzione \func{fork} per creare ad ogni
+richiesta da parte di un client un processo figlio che si incarichi della
+gestione della comunicazione. Si è allora riscritto il server \texttt{daytime}
+dell'esempio precedente in forma concorrente, inserendo anche una opzione per
+la stampa degli indirizzi delle connessioni ricevute.
+
+In \figref{fig:TCP_serv_code} è mostrato un estratto del codice, in cui si
+sono tralasciati il trattamento delle opzioni e le parti rimaste invariate
+rispetto al precedente esempio (cioè tutta la parte riguardante l'apertura
+passiva del socket). Al solito il sorgente completo del server
+\file{ElemDaytimeTCPCuncServ.c} è allegato insieme ai sorgenti degli altri
+esempi.