-
- \bodydesc{Entrambe le funzioni ritornano 0 in caso di successo e -1 in caso
- di errore, nel qual caso \var{errno} può assumere i valori:
- \begin{errlist}
- \item[\errcode{ESRCH}] si è fatto riferimento ad un processo inesistente.
- \item[\errcode{EPERM}] si è tentato di aggiungere una capacità
- nell'insieme delle \textit{capabilities} permesse, o di impostare una
- capacità non presente nell'insieme di quelle permesse negli insieme
- delle effettive o ereditate, o si è cercato di impostare una
- \textit{capability} di un altro processo senza avare
- \const{CAP\_SETPCAP}.
- \end{errlist}
- ed inoltre \errval{EFAULT} ed \errval{EINVAL}.
-}
-\end{functions}
-
-Queste due funzioni prendono come argomenti due tipi di dati dedicati,
-definiti come puntatori a due strutture specifiche di Linux, illustrate in
-fig.~\ref{fig:cap_kernel_struct}. Per un certo periodo di tempo era anche
-indicato che per poterle utilizzare fosse necessario che la macro
-\macro{\_POSIX\_SOURCE} risultasse non definita (ed era richiesto di inserire
-una istruzione \texttt{\#undef \_POSIX\_SOURCE} prima di includere
-\texttt{sys/capability.h}) requisito che non risulta più presente.\footnote{e
- non è chiaro neanche quanto sia mai stato davvero necessario.}
-
-Si tenga presente che le strutture di fig.~\ref{fig:cap_kernel_struct}, come i
-prototipi delle due funzioni \func{capget} e \func{capset}, sono soggette ad
-essere modificate con il cambiamento del kernel (in particolare i tipi di dati
-delle strutture) ed anche se finora l'interfaccia è risultata stabile, non c'è
-nessuna assicurazione che questa venga mantenuta,\footnote{viene però
- garantito che le vecchie funzioni continuino a funzionare.} Pertanto se si
-vogliono scrivere programmi portabili che possano essere eseguiti senza
-modifiche o adeguamenti su qualunque versione del kernel è opportuno
-utilizzare le interfacce di alto livello che vedremo più avanti.
-
-\begin{figure}[!htb]
- \footnotesize
- \centering
- \begin{minipage}[c]{\textwidth}
- \includestruct{listati/cap_user_header_t.h}
- \end{minipage}
- \normalsize
- \caption{Definizione delle strutture a cui fanno riferimento i puntatori
- \structd{cap\_user\_header\_t} e \structd{cap\_user\_data\_t} usati per
- l'interfaccia di gestione di basso livello delle \textit{capabilities}.}
- \label{fig:cap_kernel_struct}
-\end{figure}
-
-La struttura a cui deve puntare l'argomento \param{hdrp} serve ad indicare,
-tramite il campo \var{pid}, il PID del processo del quale si vogliono leggere
-o modificare le \textit{capabilities}. Con \func{capset} questo, se si usano
-le \textit{file capabilities}, può essere solo 0 o PID del processo chiamante,
-che sono equivalenti. Il campo \var{version} deve essere impostato al valore
-della versione delle stesse usata dal kernel (quello indicato da una delle
-costanti \texttt{\_LINUX\_CAPABILITY\_VERSION\_n} di
-fig.~\ref{fig:cap_kernel_struct}) altrimenti le funzioni ritorneranno con un
-errore di \errcode{EINVAL}, restituendo nel campo stesso il valore corretto
-della versione in uso. La versione due è comunque deprecata e non deve essere
-usata (il kernel stamperà un avviso). I valori delle \textit{capabilities}
-devono essere passati come maschere binarie;\footnote{e si tenga presente che
- i valori di tab.~\ref{tab:proc_capabilities} non possono essere combinati
- direttamente, indicando il numero progressivo del bit associato alla
- relativa capacità.} con l'introduzione delle \textit{capabilities} a 64 bit
-inoltre il puntatore \param{datap} non può essere più considerato come
-relativo ad una singola struttura, ma ad un vettore di due
-strutture.\footnote{è questo cambio di significato che ha portato a deprecare
- la versione 2, che con \func{capget} poteva portare ad un buffer overflow
- per vecchie applicazioni che continuavano a considerare \param{datap} come
- puntatore ad una singola struttura.}
-
-Dato che le precedenti funzioni, oltre ad essere specifiche di Linux, non
-garantiscono la stabilità nell'interfaccia, è sempre opportuno effettuare la
-gestione delle \textit{capabilities} utilizzando le funzioni di libreria a
-questo dedicate. Queste funzioni, che seguono quanto previsto nelle bozze
-dello standard POSIX.1e, non fanno parte delle \acr{glibc} e sono fornite in
-una libreria a parte,\footnote{la libreria è \texttt{libcap2}, nel caso di
- Debian può essere installata con il pacchetto omonimo.} pertanto se un
-programma le utilizza si dovrà indicare esplicitamente l'uso della suddetta
-libreria attraverso l'opzione \texttt{-lcap} del compilatore.
-
-Le funzioni dell'interfaccia delle bozze di POSIX.1e prevedono l'uso di un
-\index{tipo!opaco} tipo di dato opaco, \type{cap\_t}, come puntatore ai dati
-mantenuti nel cosiddetto \textit{capability state},\footnote{si tratta in
- sostanza di un puntatore ad una struttura interna utilizzata dalle librerie,
- i cui campi non devono mai essere acceduti direttamente.} in sono
-memorizzati tutti i dati delle \textit{capabilities}. In questo modo è
-possibile mascherare i dettagli della gestione di basso livello, che potranno
-essere modificati senza dover cambiare le funzioni dell'interfaccia, che
-faranno riferimento soltanto ad oggetti di questo tipo. L'interfaccia
-pertanto non soltanto fornisce le funzioni per modificare e leggere le
-\textit{capabilities}, ma anche quelle per gestire i dati attraverso
-\type{cap\_t}.
-
-La prima funzione dell'interfaccia è quella che permette di inizializzare un
-\textit{capability state}, allocando al contempo la memoria necessaria per i
-relativi dati. La funzione è \funcd{cap\_init} ed il suo prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{cap\_t cap\_init(void)}
- Crea ed inizializza un \textit{capability state}.
-
- \bodydesc{La funzione ritorna un valore non nullo in caso di successo e
- \val{NULL} in caso di errore, nel qual caso \var{errno} assumerà il
- valore \errval{ENOMEM}.
- }
-\end{functions}
-
-La funzione restituisce il puntatore \type{cap\_t} ad uno stato inizializzato
-con tutte le \textit{capabilities} azzerate. In caso di errore (cioè quando
-non c'è memoria sufficiente ad allocare i dati) viene restituito \val{NULL}
-ed \var{errno} viene impostata a \errval{ENOMEM}. La memoria necessaria a
-mantenere i dati viene automaticamente allocata da \func{cap\_init}, ma dovrà
-essere disallocata esplicitamente quando non è più necessaria utilizzando, per
-questo l'interfaccia fornisce una apposita funzione, \funcd{cap\_free}, il cui
-prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{int cap\_free(void *obj\_d)}
- Disalloca la memoria allocata per i dati delle \textit{capabilities}.
-
- \bodydesc{La funzione ritorna 0 in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà il valore \errval{EINVAL}.
- }
-\end{functions}
-
-La funzione permette di liberare la memoria allocata dalle altre funzioni
-della libreria sia per un \textit{capability state}, nel qual caso l'argomento
-dovrà essere un dato di tipo \type{cap\_t}, che per una descrizione testuale
-dello stesso,\footnote{cioè quanto ottenuto tramite la funzione
- \func{cap\_to\_text}.} nel qual caso l'argomento dovrà essere un dato di
-tipo \texttt{char *}. Per questo motivo l'argomento \param{obj\_d} è
-dichiarato come \texttt{void *} e deve sempre corrispondere ad un puntatore
-ottenuto tramite le altre funzioni della libreria, altrimenti la funzione
-fallirà con un errore di \errval{EINVAL}.
-
-Infine si può creare una copia di un \textit{capability state} ottenuto in
-precedenza tramite la funzione \funcd{cap\_dup}, il cui prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{cap\_t cap\_dup(cap\_t cap\_p)}
- Duplica un \textit{capability state} restituendone una copia.
-
- \bodydesc{La funzione ritorna un valore non nullo in caso di successo e
- \val{NULL} in caso di errore, nel qual caso \var{errno} potrà assumere i
- valori \errval{ENOMEM} o \errval{EINVAL}.
- }
-\end{functions}
-
-La funzione crea una copia del \textit{capability state} posto all'indirizzo
-\param{cap\_p} che si è passato come argomento, restituendo il puntatore alla
-copia, che conterrà gli stessi valori delle \textit{capabilities} presenti
-nell'originale. La memoria necessaria viene allocata automaticamente dalla
-funzione. Una volta effettuata la copia i due \textit{capability state}
-potranno essere modificati in maniera completamente
-indipendente.\footnote{alla fine delle operazioni si ricordi però di
- disallocare anche la copia, oltre all'originale. }
-
-Una seconda classe di funzioni di servizio previste dall'interfaccia sono
-quelle per la gestione dei dati contenuti all'interno di un \textit{capability
- state}; la prima di queste è \funcd{cap\_clear}, il cui prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{int cap\_clear(cap\_t cap\_p)}
- Inizializza un \textit{capability state} cancellando tutte le
- \textit{capabilities}.
-
- \bodydesc{La funzione ritorna 0 in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà il valore \errval{EINVAL}.
- }
-\end{functions}
-
-La funzione si limita ad azzerare tutte le \textit{capabilities} presenti nel
-\textit{capability state} all'indirizzo \param{cap\_p} passato come argomento,
-restituendo uno stato \textsl{vuoto}, analogo a quello che si ottiene nella
-creazione con \func{cap\_init}.
-
-\begin{table}[htb]
- \centering
- \footnotesize
- \begin{tabular}[c]{|l|l|}
- \hline
- \textbf{Valore} & \textbf{Significato} \\
- \hline
- \hline
- \const{CAP\_EFFECTIVE} & Capacità dell'insieme \textsl{effettivo}.\\
- \const{CAP\_PERMITTED} & Capacità dell'insieme \textsl{permesso}.\\
- \const{CAP\_INHERITABLE}& Capacità dell'insieme \textsl{ereditabile}.\\
- \hline
- \end{tabular}
- \caption{Valori possibili per il tipo di dato \type{cap\_flag\_t} che
- identifica gli insiemi delle \textit{capabilities}.}
- \label{tab:cap_set_identifier}
-\end{table}
-
-Una variante di \func{cap\_clear} è \funcd{cap\_clear\_flag} che cancella da
-un \textit{capability state} tutte le \textit{capabilities} di un certo
-insieme fra quelli di pag.~\pageref{sec:capabilities_set}, il suo prototipo
-è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{int cap\_clear\_flag(cap\_t cap\_p, cap\_flag\_t flag)}
-
- Cancella dal \textit{capability state} \param{cap\_p} tutte le
- \textit{capabilities} dell'insieme \param{flag}.
-
- \bodydesc{La funzione ritorna 0 in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà il valore \errval{EINVAL}. }
-\end{functions}
-
-La funzione richiede che si indichi quale degli insiemi si intente cancellare
-con l'argomento \param{flag}. Questo deve essere specificato con una variabile
-di tipo \type{cap\_flag\_t} che può assumere esclusivamente\footnote{si tratta
- in effetti di un tipo enumerato, come si può verificare dalla sua
- definizione che si trova in \texttt{/usr/include/sys/capability.h}.} uno dei
-valori illustrati in tab.~\ref{tab:cap_set_identifier}.
-
-Si possono inoltre confrontare in maniera diretta due diversi
-\textit{capability state} con la funzione \funcd{cap\_compare}; il suo
-prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
- \funcdecl{int cap\_compare(cap\_t cap\_a, cap\_t cap\_b)}
-
- Confronta due \textit{capability state}.
-
- \bodydesc{La funzione ritorna 0 se i \textit{capability state} sono identici
- ed un valore positivo se differiscono, non sono previsti errori.}
-\end{functions}
-
-La funzione esegue un confronto fra i due \textit{capability state} passati
-come argomenti e ritorna in un valore intero il risultato, questo è nullo se
-sono identici o positivo se vi sono delle differenze. Il valore di ritorno
-della funzione consente inoltre di per ottenere ulteriori informazioni su
-quali sono gli insiemi di \textit{capabilities} che risultano differenti. Per
-questo si può infatti usare la apposita macro \macro{CAP\_DIFFERS}:
-\begin{functions}
- \funcdecl{int CAP\_DIFFERS(value, flag)} Controlla lo stato di eventuali
- differenze delle \textit{capabilities} nell'insieme \texttt{flag}.
-\end{functions}
-
-La macro che richiede si passi nell'argomento \texttt{value} il risultato
-della funzione \func{cap\_compare} e in \texttt{flag} l'indicazione (coi
-valori di tab.~\ref{tab:cap_set_identifier}) dell'insieme che si intende
-controllare; restituirà un valore diverso da zero se le differenze rilevate da
-\func{cap\_compare} sono presenti nell'insieme indicato.
-
-Per la gestione dei singoli valori delle \textit{capabilities} presenti in un
-\textit{capability state} l'interfaccia prevede due funzioni specifiche,
-\funcd{cap\_get\_flag} e \funcd{cap\_set\_flag}, che permettono
-rispettivamente di leggere o impostare il valore di una capacità all'interno
-in uno dei tre insiemi già citati; i rispettivi prototipi sono:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{int cap\_get\_flag(cap\_t cap\_p, cap\_value\_t cap, cap\_flag\_t
- flag, cap\_flag\_value\_t *value\_p)}
- Legge il valore di una \textit{capability}.
-
- \funcdecl{int cap\_set\_flag(cap\_t cap\_p, cap\_flag\_t flag, int ncap,
- cap\_value\_t *caps, cap\_flag\_value\_t value)}
- Imposta il valore di una \textit{capability}.
-
- \bodydesc{Le funzioni ritornano 0 in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà il valore \errval{EINVAL}.
-}
-\end{functions}
-
-In entrambe le funzioni l'argomento \param{cap\_p} indica il puntatore al
-\textit{capability state} su cui operare, mentre l'argomento \param{flag}
-indica su quale dei tre insiemi si intende operare, sempre con i valori di
-tab.~\ref{tab:cap_set_identifier}.
-
-La capacità che si intende controllare o impostare invece deve essere
-specificata attraverso una variabile di tipo \type{cap\_value\_t}, che può
-prendere come valore uno qualunque di quelli riportati in
-tab.~\ref{tab:proc_capabilities}, in questo caso però non è possibile
-combinare diversi valori in una maschera binaria, una variabile di tipo
-\type{cap\_value\_t} può indicare una sola capacità.\footnote{in
- \texttt{sys/capability.h} il tipo \type{cap\_value\_t} è definito come
- \ctyp{int}, ma i valori validi sono soltanto quelli di
- tab.~\ref{tab:proc_capabilities}.}
-
-Infine lo stato di una capacità è descritto ad una variabile di tipo
-\type{cap\_flag\_value\_t}, che a sua volta può assumere soltanto
-uno\footnote{anche questo è un tipo enumerato.} dei valori di
-tab.~\ref{tab:cap_value_type}.
-
-\begin{table}[htb]
- \centering
- \footnotesize
- \begin{tabular}[c]{|l|l|}
- \hline
- \textbf{Valore} & \textbf{Significato} \\
- \hline
- \hline
- \const{CAP\_CLEAR}& La capacità non è impostata.\\
- \const{CAP\_SET} & La capacità è impostata.\\
- \hline
- \end{tabular}
- \caption{Valori possibili per il tipo di dato \type{cap\_flag\_value\_t} che
- indica lo stato di una capacità.}
- \label{tab:cap_value_type}
-\end{table}
-
-La funzione \func{cap\_get\_flag} legge lo stato della capacità indicata
-dall'argomento \param{cap} all'interno dell'insieme indicato dall'argomento
-\param{flag} lo restituisce nella variabile puntata
-dall'argomento \param{value\_p}. Questa deve essere di tipo
-\type{cap\_flag\_value\_t} ed assumerà uno dei valori di
-tab.~\ref{tab:cap_value_type}. La funzione consente pertanto di leggere solo
-lo stato di una capacità alla volta.
-
-La funzione \func{cap\_set\_flag} può invece impostare in una sola chiamata
-più \textit{capabilities}, anche se solo all'interno dello stesso insieme ed
-allo stesso valore. Per questo motivo essa prende un vettore di valori di tipo
-\type{cap\_value\_t} nell'argomento \param{caps}, la cui dimensione viene
-specificata dall'argomento \param{ncap}. Il tipo di impostazione da eseguire
-(cancellazione o impostazione) per le capacità elencate in \param{caps} viene
-indicato dall'argomento \param{value} sempre con i valori di
-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;\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}
-
- \funcdecl{char * cap\_to\_text(cap\_t caps, ssize\_t * length\_p)}
-
- Genera una visualizzazione testuale delle \textit{capabilities}.
-
- \bodydesc{La funzione ritorna un puntatore alla stringa con la descrizione
- delle \textit{capabilities} 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 ritorna l'indirizzo di una stringa contente la descrizione
-testuale del contenuto del \textit{capability state} \param{caps} passato come
-argomento, e, qualora l'argomento \param{length\_p} sia diverso da \val{NULL},
-restituisce nella variabile intera da questo puntata la lunghezza della
-stringa. La stringa restituita viene allocata automaticamente dalla funzione e
-pertanto dovrà essere liberata con \func{cap\_free}.
-
-La rappresentazione testuale, che viene usata anche di programmi di gestione a
-riga di comando, prevede che lo stato venga rappresentato con una stringa di
-testo composta da una serie di proposizioni separate da spazi, ciascuna delle
-quali specifica una operazione da eseguire per creare lo stato finale. Nella
-rappresentazione si fa sempre conto di partire da uno stato in cui tutti gli
-insiemi sono vuoti e si provvede a impostarne i contenuti.
-
-Ciascuna proposizione è nella forma di un elenco di capacità, espresso con i
-nomi di tab.~\ref{tab:proc_capabilities} separati da virgole, seguito da un
-operatore, e dall'indicazione degli insiemi a cui l'operazione si applica. I
-nomi delle capacità possono essere scritti sia maiuscoli che minuscoli, viene
-inoltre riconosciuto il nome speciale \texttt{all} che è equivalente a
-scrivere la lista completa. Gli insiemi sono identificati dalle tre lettere
-iniziali: ``\texttt{p}'' per il \textit{permitted}, ``\texttt{i}'' per
-l'\textit{inheritable} ed ``\texttt{e}'' per l'\textit{effective} che devono
-essere sempre minuscole e se ne può indicare più di uno.
-
-Gli operatori possibili sono solo tre: ``\texttt{+}'' che aggiunge le capacità
-elencate agli insiemi indicati, ``\texttt{-}'' che le toglie e ``\texttt{=}''
-che le assegna esattamente. I primi due richiedono che sia sempre indicato sia
-un elenco di capacità che gli insiemi a cui esse devono applicarsi, e
-rispettivamente attiveranno o disattiveranno le capacità elencate nell'insieme
-o negli insiemi specificati, ignorando tutto il resto. I due operatori possono
-anche essere combinati nella stessa proposizione, per aggiungere e togliere le
-capacità dell'elenco da insiemi diversi.
-
-L'assegnazione si applica invece su tutti gli insiemi allo stesso tempo,
-pertanto l'uso di ``\texttt{=}'' è equivalente alla cancellazione preventiva
-di tutte le capacità ed alla impostazione di quelle elencate negli insiemi
-specificati, questo significa che in genere lo si usa una sola volta
-all'inizio della stringa. In tal caso l'elenco delle capacità può non essere
-indicato e viene assunto che si stia facendo riferimento a tutte quante senza
-doverlo scrivere esplicitamente.
-
-Come esempi avremo allora che un processo non privilegiato di un utente, che
-non ha nessuna capacità attiva, avrà una rappresentazione nella forma
-``\texttt{=}'' che corrisponde al fatto che nessuna capacità viene assegnata a
-nessun insieme (vale la cancellazione preventiva), mentre un processo con
-privilegi di amministratore avrà una rappresentazione nella forma
-``\texttt{=ep}'' in cui tutte le capacità vengono assegnate agli insiemi
-\textit{permitted} ed \textit{effective} (e l'\textit{inheritable} è ignorato
-in quanto per le regole viste a pag.~\ref{sec:capability-uid-transition} le
-capacità verranno comunque attivate attraverso una \func{exec}). Infine, come
-esempio meno banale dei precedenti, 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} come strutture di dati;
-l'interfaccia di gestione prevede però anche le funzioni per trattare le
-\textit{capabilities} presenti nei processi. La prima di queste funzioni è
-\funcd{cap\_get\_proc} che consente la lettura delle \textit{capabilities} del
-processo corrente, il suo prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{cap\_t cap\_get\_proc(void)}
- Legge le \textit{capabilities} del processo corrente.
-
- \bodydesc{La funzione ritorna un valore diverso da \val{NULL} in caso di
- successo e \val{NULL} in caso di errore, nel qual caso \var{errno} può
- assumere i valori \errval{EINVAL}, \errval{EPERM} o \errval{ENOMEM}. }
-\end{functions}
-
-La funzione legge il valore delle \textit{capabilities} associate al processo
-da cui viene invocata, restituendo il risultato tramite il puntatore ad un
-\textit{capability state} contenente tutti i dati che provvede ad allocare
-autonomamente e che di nuovo occorrerà liberare con \func{cap\_free} quando
-non sarà più utilizzato.
-
-Se invece si vogliono leggere le \textit{capabilities} di un processo
-specifico occorre usare la funzione \funcd{capgetp}, il cui
-prototipo\footnote{su alcune pagine di manuale la funzione è descritta con un
- prototipo sbagliato, che prevede un valore di ritorno di tipo \type{cap\_t},
- ma il valore di ritorno è intero, come si può verificare anche dalla
- dichiarazione della stessa in \texttt{sys/capability.h}.} è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{int capgetp(pid\_t pid, cap\_t cap\_d)}
- Legge le \textit{capabilities} del processo indicato da \param{pid}.
-
- \bodydesc{La funzione ritorna 0 in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} può assumere i valori \errval{EINVAL},
- \errval{EPERM} o \errval{ENOMEM}.
- }
-\end{functions}
-%TODO controllare e correggere i codici di errore!!!
-
-La funzione legge il valore delle \textit{capabilities} del processo indicato
-con l'argomento \param{pid}, e restituisce il risultato nel \textit{capability
- state} posto all'indirizzo indicato con l'argomento
-\param{cap\_d}; a differenza della precedente in questo caso il
-\textit{capability state} deve essere stato creato in precedenza. Qualora il
-processo indicato non esista si avrà un errore di \errval{ESRCH}. Gli stessi
-valori possono essere letti direttamente nel filesystem \textit{proc}, nei
-file \texttt{/proc/<pid>/status}; ad esempio per \texttt{init} si otterrà
-qualcosa del tipo:
-\begin{Verbatim}
-...
-CapInh: 0000000000000000
-CapPrm: 00000000fffffeff
-CapEff: 00000000fffffeff
-...
-\end{Verbatim}
-
-Infine per impostare le \textit{capabilities} del processo corrente (non
-esiste una funzione che permetta di cambiare le \textit{capabilities} di un
-altro processo) si deve usare la funzione \funcd{cap\_set\_proc}, il cui
-prototipo è:
-\begin{functions}
- \headdecl{sys/capability.h}
-
- \funcdecl{int cap\_set\_proc(cap\_t cap\_p)}
- Imposta le \textit{capabilities} del processo corrente.
-
- \bodydesc{La funzione ritorna 0 in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} può assumere i valori \errval{EINVAL},
- \errval{EPERM} o \errval{ENOMEM}.
- }
-\end{functions}
-
-La funzione modifica le \textit{capabilities} del processo corrente secondo
-quanto specificato con l'argomento \param{cap\_p}, posto che questo sia
-possibile nei termini spiegati in precedenza (non sarà ad esempio possibile
-impostare capacità non presenti nell'insieme di quelle permesse). In caso di
-successo i nuovi valori saranno effettivi al ritorno della funzione, in caso
-di fallimento invece lo stato delle capacità resterà invariato. Si tenga
-presente che \textsl{tutte} le capacità specificate tramite \param{cap\_p}
-devono essere permesse; se anche una sola non lo è la funzione fallirà, e per
-quanto appena detto, lo stato delle \textit{capabilities} non verrà modificato
-(neanche per le parti eventualmente permesse).
-
-Come esempio di utilizzo di queste funzioni nei sorgenti allegati alla guida
-si è distribuito il programma \texttt{getcap.c}, che consente di leggere le
-\textit{capabilities} del processo corrente\footnote{vale a dire di sé stesso,
- quando lo si lancia, il che può sembrare inutile, ma serve a mostrarci quali
- sono le \textit{capabilities} standard che ottiene un processo lanciato
- dalla riga di comando.} o tramite l'opzione \texttt{-p}, quelle di un
-processo qualunque il cui pid viene passato come parametro dell'opzione.
-
-\begin{figure}[!htbp]
- \footnotesize \centering
- \begin{minipage}[c]{\codesamplewidth}
- \includecodesample{listati/getcap.c}
- \end{minipage}
- \normalsize
- \caption{Corpo principale del programma \texttt{getcap.c}.}
- \label{fig:proc_getcap}
-\end{figure}
-
-La sezione principale del programma è riportata in fig.~\ref{fig:proc_getcap},
-e si basa su una condizione sulla variabile \var{pid} che se si è usato
-l'opzione \texttt{-p} è impostata (nella sezione di gestione delle opzioni,
-che si è tralasciata) al valore del \textsl{pid} del processo di cui si vuole
-leggere le \textit{capabilities} e nulla altrimenti. Nel primo caso
-(\texttt{\small 1--6}) si utilizza direttamente (\texttt{\small 2})
-\func{cap\_get\_proc} per ottenere lo stato delle capacità del processo, nel
-secondo (\texttt{\small 7--14}) prima si inizializza (\texttt{\small 8}) uno
-stato vuoto e poi (\texttt{\small 9}) si legge il valore delle capacità del
-processo indicato.
-
-Il passo successivo è utilizzare (\texttt{\small 16}) \func{cap\_to\_text} per
-tradurre in una stringa lo stato, e poi (\texttt{\small 17}) stamparlo; infine
-(\texttt{\small 19--20}) si libera la memoria allocata dalle precedenti
-funzioni con \func{cap\_free} per poi ritornare dal ciclo principale della
-funzione.
-
-\itindend{capabilities}
-
-% TODO vedi http://lwn.net/Articles/198557/ e
-% http://www.madore.org/~david/linux/newcaps/
-
-
-
-\subsection{La funzione \func{chroot}}