Aggiunte anche mq_send e mq_receive
[gapil.git] / ipc.tex
diff --git a/ipc.tex b/ipc.tex
index 9c387da..ba47d11 100644 (file)
--- a/ipc.tex
+++ b/ipc.tex
@@ -4046,31 +4046,140 @@ due funzioni \funcd{mq\_getattr} e \funcd{mq\_setattr}, i cui prototipi sono:
   
   \funcdecl{int mq\_getattr(mqd\_t mqdes, struct mq\_attr *mqstat)}
   Legge gli attributi di una coda di messaggi POSIX.
-
   
-  \funcdecl{int mq\_setattr(mqd\_t mqdes, const struct mq\_attr *mqstat, struct
-    mq\_attr *omqstat)}
+  \funcdecl{int mq\_setattr(mqd\_t mqdes, const struct mq\_attr *mqstat,
+    struct mq\_attr *omqstat)}
   Modifica gli attributi di una coda di messaggi POSIX.
   
-  \bodydesc{La funzione restituisce il descrittore associato alla coda in caso
-    di successo e -1 in caso di errore; nel quel caso \var{errno} assumerà i
-    valori \errval{EBADF} o \errval{EINVAL}.}
+  \bodydesc{Entrambe le funzioni restituiscono 0 in caso di successo e -1 in
+    caso di errore; nel quel caso \var{errno} assumerà i valori \errval{EBADF}
+    o \errval{EINVAL}.}
 \end{functions}
 
-La funzione \func{mq\_getattr} legge i valori correnti degli attributi nella
-struttura puntata da \param{mqstat}; di questi l'unico rilevante è
-\var{mq\_curmsgs} che indica il numero di messaggi da essa contenuti.
+La funzione \func{mq\_getattr} legge i valori correnti degli attributi della
+coda nella struttura puntata da \param{mqstat}; di questi l'unico relativo
+allo stato corrente della coda è \var{mq\_curmsgs} che indica il numero di
+messaggi da essa contenuti, gli altri indicano le caratteristiche generali
+della stessa.
 
 La funzione \func{mq\_setattr} permette di modificare gli attributi di una
 coda tramite i valori contenuti nella struttura puntata da \param{mqstat}, ma
 può essere modificato solo il campo \var{mq\_flags}, gli altri campi vengono
-ignorati. In particolare i valori di \var{mq\_flags} e \var{mq\_flags} possono
-essere specificati solo in fase ci creazione della coda.  Inoltre i soli
-valori possibili per \var{mq\_flags} sono 0 e \const{O\_NONBLOCK}, per cui
-alla fine la funzione può essere utilizzata solo per abilitare o disabilitare
-la modalità non bloccante. L'argomento \param{omqstat} viene usato, quando
-diverso da \val{NULL}, per specificare l'indirizzo di una struttura su cui
-salvare i valori degli attributi precedenti alla chiamata della funzione.
+ignorati. In particolare i valori di \var{mq\_maxmsg} e \var{mq\_msgsize}
+possono essere specificati solo in fase ci creazione della coda.  Inoltre i
+soli valori possibili per \var{mq\_flags} sono 0 e \const{O\_NONBLOCK}, per
+cui alla fine la funzione può essere utilizzata solo per abilitare o
+disabilitare la modalità non bloccante. L'argomento \param{omqstat} viene
+usato, quando diverso da \val{NULL}, per specificare l'indirizzo di una
+struttura su cui salvare i valori degli attributi precedenti alla chiamata
+della funzione.
+
+Per inserire messaggi su di una coda sono previste due funzioni,
+\funcd{mq\_send} e \funcd{mq\_timedsend}, i cui prototipi sono:
+\begin{functions}
+  \headdecl{mqueue.h} 
+  
+  \funcdecl{int mq\_send(mqd\_t mqdes, const char *msg\_ptr, size\_t msg\_len,
+    unsigned int msg\_prio)} 
+  Esegue l'inserimento di un messaggio su una coda.
+  
+  \funcdecl{int mq\_timedsend(mqd\_t mqdes, const char *msg\_ptr, size\_t
+    msg\_len, unsigned msg\_prio, const struct timespec *abs\_timeout)}   
+  Esegue l'inserimento di un messaggio su una coda entro il tempo
+  \param{abs\_timeout}.
+
+  
+  \bodydesc{Le funzioni restituiscono 0 in caso di successo e -1 in caso di
+    errore; nel quel caso \var{errno} assumerà i valori:
+    \begin{errlist}
+    \item[\errcode{EAGAIN}] Si è aperta la coda con \const{O\_NONBLOCK}, e la
+      coda è piena.
+    \item[\errcode{EMSGSIZE}] La lunghezza del messaggio \param{msg\_len}
+      eccede il limite impostato per la coda.
+    \item[\errcode{ENOMEM}] Il kernel non ha memoria sufficiente. Questo
+      errore può avvenire quando l'inserimento del messaggio
+    \item[\errcode{EINVAL}] Si è specificato un valore nullo per
+      \param{msg\_len}, o un valore di \param{msg\_prio} fuori dai limiti, o
+      un valore non valido per \param{abs\_timeout}.
+    \item[\errcode{ETIMEDOUT}] L'inserimento del messaggio non è stato
+      effettuato entro il tempo stabilito.
+    \end{errlist}    
+    ed inoltre \errval{EBADF} ed \errval{EINTR}.}
+\end{functions}
+
+Entrambe le funzioni richiedono un puntatore al testo del messaggio
+nell'argomento \param{msg\_ptr} e la relativa lunghezza in \param{msg\_len}.
+Se quest'ultima eccede la dimensione massima specificata da \var{mq\_msgsize}
+le funzioni ritornano immediatamente con un errore di \errcode{EMSGSIZE}.
+
+L'argomento \param{msg\_prio} indica la priorità dell'argomento; i messaggi di
+priorità maggiore vengono inseriti davanti a quelli di priorità inferiore (e
+quindi saranno riletti per primi). A parità del valore della priorità il
+messaggio sarà inserito in coda a tutti quelli con la stessa priorità. Il
+valore della priorità non può eccedere il limite di sistema
+\const{MQ\_PRIO\_MAX}, che nel caso è pari a 32768.
+
+Qualora la coda sia piena, entrambe le funzioni si bloccano, a meno che non
+sia stata selezionata in fase di apertura la modalità non bloccante, nel qual
+caso entrambe ritornano \errcode{EAGAIN}. La sola differenza fra le due
+funzioni è che la seconda, passato il tempo massimo impostato con l'argomento
+\param{abs\_timeout}, ritorna comunque con un errore di \errcode{ETIMEDOUT}.
+
+
+Come per l'inserimento, anche per l'estrazione dei messaggi da una coda sono
+previste due funzioni, \funcd{mq\_receive} e \funcd{mq\_timedreceive}, i cui
+prototipi sono:
+\begin{functions}
+  \headdecl{mqueue.h} 
+  
+  \funcdecl{ssize\_t mq\_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len,
+    unsigned int *msg_prio)} Effettua la ricezione di un messaggio da una coda.
+  
+  \funcdecl{ssize\_t mq\_timedreceive(mqd\_t mqdes, char *msg\_ptr, size\_t
+    msg\_len, unsigned int *msg\_prio, const struct timespec *abs'_timeout)}
+  Effettua la ricezione di un messaggio da una coda entro il tempo
+  \param{abs\_timeout}.
+  
+  \bodydesc{Le funzioni restituiscono il numero di byte del messaggio in caso
+    di successo e -1 in caso di errore; nel quel caso \var{errno} assumerà i
+    valori:
+    \begin{errlist}
+    \item[\errcode{EAGAIN}] Si è aperta la coda con \const{O\_NONBLOCK}, e la
+      coda è vuota.
+    \item[\errcode{EMSGSIZE}] La lunghezza del messaggio sulla coda eccede il
+      valore \param{msg\_len} specificato per la ricezione.
+    \item[\errcode{EINVAL}] Si è specificato un valore nullo per
+      \param{msg\_ptr}, o un valore non valido per \param{abs\_timeout}.
+    \item[\errcode{ETIMEDOUT}] La ricezione del messaggio non è stata
+      effettuata entro il tempo stabilito.
+    \end{errlist}    
+    \errval{EBADF}, \errval{EINTR}, \errval{ENOMEM}, o \errval{EINVAL}.}
+\end{functions}
+
+La funzione estrae dalla coda il messaggio a priorità più alta, o il più
+vecchio fra quelli della stessa priorità, una volta ricevuto il messaggio
+viene tolto dalla coda e la sua dimensione viene restituita come valore di
+ritorno. Se la dimensione specificata da \param{msg\_len} non è sufficiente a
+contenere il messaggio le funzioni, al contrario di quanto avveniva nelle code
+di messaggi di SysV, ritornano un errore di \errcode{EMSGSIZE} senza estrarre
+il messaggio.  È pertanto opportuno chiamare sempre \func{mq\_getaddr} prima
+di eseguire una ricezione, per allocare per i messaggi dei buffer di
+dimensione opportuna.
+
+Se si specifica un valore non nullo per l'argomento \param{msg\_prio} il
+valore della priorità del messaggio viene memorizzato all'indirizzo da esso
+puntato. Si noti che con le code di messaggi POSIX non si ha la possibilità di
+selezionare quale messaggio estrarre in base alla priorità, a differenza di
+quanto avveniva con le code di messaggi di SysV che permettono la selezione in
+base al valore del campo \var{mtype}.
+
+Qualora la coda sia vuota entrambe le funzioni si bloccano, a meno che non si
+sia selezionata la modalità non bloccante; in tal caso entrambe ritornano
+immediatamente con l'errore \errcode{EAGAIN}. Anche in questo caso la sola
+differenza fra le due funzioni è che la seconda non attende indefinitamente e
+passato il tempo massimo \param{abs\_timeout} ritorna comunque con un errore
+di \errcode{ETIMEDOUT}.
+
 
 
 \subsection{Semafori}