Altre piccole aggiunte
[gapil.git] / filedir.tex
index 461bcacb47675dc6acad30db75d0c61558eee390..a48b85860f4c3d932f5510da27d5bfce06bff533 100644 (file)
@@ -5539,9 +5539,10 @@ tab.~\ref{tab:cap_value_type}.
 
 Per semplificare la gestione delle \textit{capabilities} l'interfaccia prevede
 che sia possibile utilizzare anche una rappresentazione testuale del contenuto
-di un \textit{capability state} e fornisce le opportune funzioni di gestione;
-la prima di queste, che consente di ottenere la rappresentazione testuale, è
-\funcd{cap\_to\_text}, il cui prototipo è:
+di un \textit{capability state} e fornisce le opportune funzioni di
+gestione;\footnote{entrambe erano previste dalla bozza dello standard
+  POSIX.1e.} la prima di queste, che consente di ottenere la rappresentazione
+testuale, è \funcd{cap\_to\_text}, il cui prototipo è:
 \begin{functions}
   \headdecl{sys/capability.h}
 
@@ -5610,6 +5611,53 @@ meno banale, otterremo per \texttt{init} una rappresentazione nella forma
 ``\texttt{=ep cap\_setpcap-e}'' dato che come accennato tradizionalmente
 \const{CAP\_SETPCAP} è sempre stata rimossa da detto processo.
 
+Viceversa per passare ottenere un \textit{capability state} dalla sua
+rappresentazione testuale si può usare \funcd{cap\_from\_text}, il cui
+prototipo è:
+\begin{functions}
+  \headdecl{sys/capability.h}
+
+  \funcdecl{cap\_t cap\_from\_text(const char *string)}
+
+  Crea un \textit{capability state} dalla sua rappresentazione testuale.
+
+  \bodydesc{La funzione ritorna un puntatore valido in caso di successo e
+    \val{NULL} in caso di errore, nel qual caso \var{errno} può assumere i
+    valori \errval{EINVAL} o \errval{ENOMEM}.}
+\end{functions}
+
+La funzione restituisce il puntatore ad un \textit{capability state}
+inizializzato con i valori indicati nella stringa \param{string} che ne
+contiene la rappresentazione testuale. La memoria per il \textit{capability
+  state} viene allocata automaticamente dalla funzione e dovrà essere liberata
+con \func{cap\_free}.
+
+Alle due funzioni citate se ne aggiungono altre due che consentono di
+convertire i valori delle costanti di tab.~\ref{tab:proc_capabilities} nelle
+stringhe usate nelle rispettive rappresentazioni e viceversa. Le due funzioni,
+\func{cap\_to\_name} e \func{cap\_from\_name}, sono estensioni specifiche di
+Linux ed i rispettivi prototipi sono:
+\begin{functions}
+  \headdecl{sys/capability.h}
+
+  \funcdecl{char * cap\_to\_name(cap\_value\_t cap)}
+  \funcdecl{int cap\_from\_name(const char *name, cap\_value\_t *cap\_p)}
+  Convertono le \textit{capabilities} dalle costanti alla rappresentazione
+  testuale e viceversa.
+  
+  \bodydesc{La funzione \func{cap\_to\_name} ritorna un valore diverso da
+    \val{NULL} in caso di successo e \val{NULL} in caso di errore, mentre
+    \func{cap\_to\_name} ritorna rispettivamente 0 e $-1$, per entrambe in
+    caso di errore \var{errno} può assumere i valori \errval{EINVAL} o
+    \errval{ENOMEM}.  }
+\end{functions}
+
+La prima funzione restituisce la stringa (allocata automaticamente e che dovrà
+essere liberata con \func{cap\_free}) che corrisponde al valore della
+capacità \param{cap}, mentre la seconda restituisce nella variabile puntata
+da \param{cap\_p} il valore della capacità rappresentata dalla
+stringa \param{name}.
+
 Fin quei abbiamo trattato solo le funzioni di servizio relative alla
 manipolazione dei \textit{capability state}; l'interfaccia di gestione prevede
 però anche le funzioni per la gestione delle \textit{capabilities} stesse. La