libSOCK
NAME

        LibSOCK -  Machine independent Socket I/O functions.

PUBLIC APIs
	SOCK_Accept
	SOCK_Client
	SOCK_HAddr
	SOCK_HAddrSI
	SOCK_Listen
	SOCK_Read
	SOCK_SAddr
	SOCK_Server
	SOCK_ServerF
	SOCK_SetTout, SOCK_GetTout
	SOCK_Write


SYNOPSIS
	
	int SOCK_Accept (int baseSock)

DESCRIPTION

	Accepts a connection on a socket returned by SOCK_Listen().
	Return a connected socket or -1.
SYNOPSIS
	
	int SOCK_Client (char *hostn, int portn, int retry)
DESCRIPTION
Apre un socket e lo connette alla porta/macchina date.
- hostn: Nome della macchina (/etc/hosts) a cui ci si
vuole collegare.
- portn: numero di porta;
- retry: numero di ritentativi a distanza di RTT sec.
1 sec per default, riassegnabile dall'esterno mediante
SOCK_SetTout(). Se retry==0 => nessun ritentativo.
Connect() e` una chiamata sospensiva la cui durata, in
caso di mancata connessione dipende dai timeout interni
del TCP, tipicamente brevissimi. Talvolta pero` arrivano
a vari minuti (e non c'e`l'API per modificarli).
Quindi retry = n significa:
- n ritentativi istantanei intervallati da sleep di RTT
sec, se il TCP ha timeout brevi, OPPURE
- un tentativo con timeout (alarm) di ((n+1) * RTT) sec,
se il TCP e` configurato con dei timeout da WAN.
Dunque, comunque sia settato il TCP, il parametro "retry"
fissa la DURATA MASSIMA della chiamata.
Return: socket descr. (>0) se ha successo, -1 se fallisce.
SYNOPSIS

	int SOCK_HAddr  (char *hostn)

DESCRIPTION

	Returns the IP address of the host or 0 if the host doesn't exist (in the local database).
SYNOPSIS
int SOCK_HAddrSI (char *hostn, char *ip_str, int *ip_int)
DESCRIPTION
Restituisce l'indirizzo IP dell' host indicato in forma ASCII
puntata e integer in network
byte order nei parametri indirizzati da puntatori non nulli.
Return: 0 e indirizzo caricato, se l'host esiste; -1 e
parametri di uscita invariata se l'host non esiste
o se sono stati rilevati altri errori di basso li-
vello.
SYNOPSYS
int SOCK_Listen (int portn, int retry)
DESCRIPTION

Opens a socket for accept and returns it just after the
listen() call. Useful for accpting connections on select()
events.
Input: portn: numero di porta;
retry: numero di ritentativi a distanza di 3 secondi,
in caso di errore ( retry <= 0 significa nessun ritentativo).
Notare che esegue una accept() sospensiva, quindi
NON fa polling ogni RTT secondi: i retry vengono
spesi solo in caso di errore, con pause di RTT sec.
Output: socket file descriptor (>0) se ha successo, -1 se fallisce.
FILE
SOCK_Server.c


SYNOPSIS
int SOCK_Read (int sd, char *pbuf, int size, int tout)
DESCRIPTION


// Descrizione:	Legge con timeout il numero di caratteri richiesti e li
//				carica all'indirizzo indicato effettuando eventuali read
//				parziali.
//

// Input:		sd:		socket id.
//				pbuf:	indirizzo del buffer utente. E` responsabilita`
//						del programma chiamante indicare un'area di almeno
//						"size" byte.
// 				size:	numero di caratteri da leggere.
//              tout:	durata max del completamento. Non vengono gestite
//						eventuali "alarm" gia` attive al momento della
//						chiamata. Se "tout" <= 0 non viene attivato alcun
//						meccanismo di timeout.
//
// Output:	 0:	quando sono stati effettivamente letti "syze" byte.
//			 1:	quando sono stati effettivamente letti "size" byte ed e`
//				stato riconosciuto l'arrivo di un signal non gestito da
//				questa procedura ma, evidentemente,	intrappolato a livello
//				piu` alto (vedi ret == -3).
//				Notare che quando "tout" <= 0, anche il SIGALRM e` conside-
//				rato "esterno" e provoca return 1 o -3.
//			-1:	in caso di errore di I/O (caduta del socket per terminazio-
//				ne del processo produttore o altro motivo, socket non aper-
//				to, parametri sbagliati etc.)
//			-2:	quando non e` stata effettuata alcuna lettura, a causa
//				dello scadere del timeout; possibile solo se "tout" > 0.
//			-3:	quando non e` stata effettuata alcuna lettura, a causa di
//				un signal esterno (vedi caso return == 1).
//
//  NOTE:		Se viene indicato "tout" > 0, qualunque sia l'esito finale,
//			    viene disabilitata la alarm, senza tener conto di eventuali
//				timeout preesistenti; la routine di gestione SIGALRM viene
//				invece ripristinata correttamente.
//
//				La variabile "errno" riflette sempre il reale andamento
//				della chiamata a meno dei casi:
//					(return -1) && (errno == 0) ===> socket down
//					(return -2) && (errno == 0) ===> timeout
SYNOPSIS
int SOCK_SAddr (int sd, char *ip_str, int *ip_int)
DESCRIPTION
Dato un descrittore socket, restituisce l'indirizzo IP del-
l'host connesso in:
- ip_str: formato ASCII puntatose, se ip_str e` non nullo.
- ip_int: formato intero, se ip_int e` non nullo.
Restituisce 0 se non ci sono errori, se non -1 + errno.
Se entrmbi gli argomenti di output sono nulli, non resti-
tuisce nulla, indica solo se il socket e` aperto o no.

SYNOPSIS
int SOCK_Server (int portn, int retry)
DESCRIPTION
Apre un socket in modo "server" sulla porta indicata, e
mette in ascolto. Quando accetta una connessione,
restituisce il descrittore del socket connesso al client.
Input: portn: numero di porta;
retry: numero di ritentativi a distanza di 3 secondi,
in caso di errore ( retry <= 0 significa nessun ri-
tentativo).
Notare che esegue una accept() sospensiva, quindi
NON fa polling ogni RTT secondi: i retry vengono
spesi solo in caso di errore, con pause di RTT sec.
Output: socket file descriptor (>0) se ha successo, -1 se fallisce.
FILE
SOCK_Server.c

SYNOPSYS
int SOCK_ServerF (int portn, int retry)
DESCRIPTION

Apre un socket in modo "server" sulla porta indicata, e
mette in ascolto. Quando accetta una connessione, esegue
una "fork". Il processo padre continua ad ascoltare (non
esce mai dalla procedura); il processo figlio termina la
procedura restituendo il descrittore del socket connesso
al client "accettato" dal padre.

Input: portn: numero di porta;
retry: numero di ritentativi a distanza di 3 secondi,
in caso di errore ( retry <= 0 significa nessun ri-
tentativo).
Notare che esegue una accept() sospensiva, quindi
NON fa polling ogni RTT secondi: i retry vengono
spesi solo in caso di errore, con pause di RTT sec.
Output: socket file descriptor (>0) se ha successo, -1 se fallisce.
FILE
SOCK_Server.c
SYNOPSIS
int SOCK_GetTout (void)
int SOCK_SetTout(int tout)
DESCRIPTION

FILE
SOCK_Tout.c

SYNOPSIS
int SOCK_Write (int sd, char *pbuf, int size, int tout)
DESCRIPTION

Scrive con timeout il numero di caratteri richiesti prele-
//				vandoli dall'indirizzo indicato.
//				Se non riesce a soddisfare la richiesta con una singola
//				"write" di basso livello, effettua delle scritture parziali.
//

// Input:		sd:		socket id.
//				pbuf:	indirizzo del buffer utente. E` responsabilita`
//						del programma chiamante indicare un'area di almeno
//						"size" byte.
// 		 		size:	numero di caratteri da scrivere.
//              tout:	durata max del completamento. Non vengono gestite
//						eventuali "alarm" gia` attive al momento della
//						chiamata. Se "tout" <= 0 non viene attivato alcun
//						meccanismo interno di timeout.
//
// Output:	 0:	quando sono stati effettiv. scritti "syze" byte.
//			-1:	in caso di errore di I/O (caduta del socket per terminazio-
//				ne del processo produttore o altro motivo, socket non
//				aperto, parametri sbagliati etc.)
//			-2: in caso di timeout; possibile solo se "tout" > 0.
//			-3: se la scrittura e` stata interrotta da un signal non gesti-
//				to da questa procedura ma, evidentemente, intrappolato a
//				livello piu` alto.
//				Notare che quando "tout" <= 0, anche il SIGALRM	e` conside-
//				rato "esterno" e provoca return(-3).
//
//  Side Eff.:	Se viene indicato "tout" > 0, qualunque sia l'esito finale,
//			    viene disabilitata la alarm, senza tener conto di eventuali
//				timeout preesistenti; la routine di gestione SIGALRM viene
//				invece ripristinata correttamente.
//
//				La routine di gestione SIGPIPE viene sempre ripristinata.
//
//				La variabile "errno" riflette sempre il reale andamento
//				della chiamata a meno del caso:
//					(return -1) && (errno == EINTR) ===> socket down
//