\fdesc{Inizializza un'area di lavoro per una ACL.}
}
-{La funzione ritorna un puntatore all'area di lavoro in caso di successo e
+{La funzione ritorna un oggetto di tipo \type{acl\_t} in caso di successo e
\val{NULL} per un errore, nel qual caso \var{errno} assumerà uno dei valori:
\begin{errlist}
\item[\errcode{EINVAL}] il valore di \param{count} è negativo.
mantenere i dati di una ACL contenente fino ad un massimo di \param{count}
voci. La funzione ritorna un valore di tipo \type{acl\_t} da usare in tutte le
altre funzioni che operano sulla ACL. La funzione si limita alla allocazione
-iniziale e non inserisce nessun valore nella ACL che resta vuota. Si tenga
-presente che pur essendo \type{acl\_t} un \index{tipo!opaco} tipo opaco che
-identifica ``\textsl{l'oggetto}'' ACL, il valore restituito dalla funzione non
-è altro che un puntatore all'area di memoria allocata per i dati richiesti;
-pertanto in caso di fallimento verrà restituito un puntatore nullo e si dovrà
-confrontare il valore di ritorno della funzione con ``\code{(acl\_t) NULL}''.
+iniziale e non inserisce nessun valore nella ACL che resta vuota.
+
+Si tenga presente che pur essendo \type{acl\_t} un \index{tipo!opaco} tipo
+opaco che identifica ``\textsl{l'oggetto}'' ACL, il valore restituito dalla
+funzione non è altro che un puntatore all'area di memoria allocata per i dati
+richiesti. Pertanto in caso di fallimento verrà restituito un puntatore nullo
+e si dovrà, in questa come in tutte le funzioni seguenti che restituiscono un
+oggetto di tipo \type{acl\_t}, confrontare il valore di ritorno della funzione
+con ``\code{(acl\_t) NULL}''.\footnote{dato che il valore \var{NULL} in questo
+ caso viene restituito come oggetto di tipo \type{acl\_t}, un confronto del
+ risultato della funzione con \var{NULL} darebbe un errore di compilazione
+ per la differenza di tipo.}
Una volta che si siano completate le operazioni sui dati di una ACL la memoria
-allocata dovrà essere liberata esplicitamente attraverso una chiamata alla
-funzione \funcd{acl\_free}, il cui prototipo è:
+allocata per un oggetto \type{acl\_t} dovrà essere liberata esplicitamente
+attraverso una chiamata alla funzione \funcd{acl\_free}, il cui prototipo è:
\begin{funcproto}{
\fhead{sys/types.h}
}
{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
- caso \var{errno} assumerà il valore \errcode{EINVAL} se \param{obj\_p} non è
- valido.}
+ caso \var{errno} assumerà il valore:
+ \begin{errlist}
+ \item[\errcode{EINVAL}] \param{obj\_p} non è valido.
+ \end{errlist}
+}
\end{funcproto}
-Si noti come la funzione richieda come argomento un puntatore di tipo
-``\ctyp{void *}'', essa infatti può essere usata non solo per liberare la
-memoria allocata per i dati di una ACL, ma anche per quella usata per creare
-le stringhe di descrizione testuale delle ACL o per ottenere i valori dei
-qualificatori di una voce; pertanto a seconda dei casi occorrerà eseguire un
-\textit{cast} a ``\ctyp{void *}'' del tipo di dato di cui si vuole eseguire la
-disallocazione. Si tenga presente poi che oltre a \func{acl\_init} esistono
-molte altre funzioni che possono allocare memoria per i dati delle ACL, è
-pertanto opportuno tenere traccia di tutte queste funzioni perché alla fine
-delle operazioni tutta la memoria allocata dovrà essere liberata con
+Si noti come la funzione usi come argomento un puntatore di tipo ``\ctyp{void
+ *}'', essa infatti può essere usata non solo per liberare la memoria
+allocata per i dati di una ACL, ma anche per quella usata per creare le
+stringhe di descrizione testuale delle ACL o per ottenere i valori dei
+qualificatori della una voce di una ACL.
+
+Pertanto a seconda dei casi occorrerà eseguire un \textit{cast} a ``\ctyp{void
+ *}'' del tipo di dato di cui si vuole eseguire la disallocazione. Si tenga
+presente poi che oltre a \func{acl\_init} ci sono molte altre funzioni che
+possono allocare memoria per i dati delle ACL, è pertanto opportuno tenere
+traccia di tutte le chiamate a queste funzioni perché alla fine delle
+operazioni tutta la memoria allocata dovrà essere liberata con
\func{acl\_free}.
Una volta che si abbiano a disposizione i dati di una ACL tramite il
}
{La funzione ritorna un oggetto di tipo \type{acl\_t} in caso di successo in
- caso di successo e \code{(acl\_t)NULL} per un errore, nel qual caso
- \var{errno} assumerà assumerà uno dei valori:
+ caso di successo e \val{NULL} per un errore, nel qual caso \var{errno}
+ assumerà assumerà uno dei valori:
\begin{errlist}
\item[\errcode{EINVAL}] l'argomento \param{acl} non è un puntatore valido
per una ACL.
}
{La funzione ritorna un oggetto di tipo \type{acl\_t} in caso di successo e
- \code{(acl\_t)NULL} per un errore, nel qual caso \var{errno} potra assumere
+ \val{NULL} per un errore, nel qual caso \var{errno} potra assumere
solo il valore \errval{ENOMEM} nel suo significato generico.}
\end{funcproto}
}
{La funzione ritorna un oggetto di tipo \type{acl\_t} in caso di successo e
- \code{(acl\_t)NULL} per un errore, nel qual caso \var{errno} assumerà uno
+ \val{NULL} per un errore, nel qual caso \var{errno} assumerà uno
dei valori:
\begin{errlist}
\item[\errcode{ENOMEM}] non c'è memoria sufficiente per allocare i dati.
}
{La funzione ritorna un oggetto di tipo \type{acl\_t} in caso di successo e
- \code{(acl\_t)NULL} per un errore, nel qual caso \var{errno} assumerà uno
+ \val{NULL} per un errore, nel qual caso \var{errno} assumerà uno
dei valori:
\begin{errlist}
\item[\errcode{ENOMEM}] non c'è memoria sufficiente per allocare i dati.
prevede due diverse forme, estesa e breve, entrambe supportate da
\func{acl\_from\_text}. La forma estesa prevede che sia specificata una voce
per riga, nella forma:
-\begin{Verbatim}
- tipo:qualificatore:permessi
-\end{Verbatim}
+\begin{Example}
+tipo:qualificatore:permessi
+\end{Example}
dove il tipo può essere uno fra \texttt{user}, \texttt{group}, \texttt{other}
e \texttt{mask}. Il qualificatore è presente solo per \texttt{user} e
\texttt{group} e indica l'utente o il gruppo a cui la voce si riferisce; i
permessi sono espressi con una tripletta di lettere analoga a quella usata per
-i permessi dei file.\footnote{vale a dire \texttt{r} per il permesso di
- lettura, \texttt{w} per il permesso di scrittura, \texttt{x} per il permesso
- di esecuzione (scritti in quest'ordine) e \texttt{-} per l'assenza del
- permesso.}
+i permessi dei file.\footnote{vale a dire ``\texttt{r}'' per il permesso di
+ lettura, ``\texttt{w}'' per il permesso di scrittura, ``\texttt{x}'' per il
+ permesso di esecuzione (scritti in quest'ordine) e ``\texttt{-}'' per
+ l'assenza del permesso.}
Va precisato che i due tipi \texttt{user} e \texttt{group} sono usati
rispettivamente per indicare delle voci relative ad utenti e
argomento, ed alloca automaticamente la memoria necessaria. Questa dovrà poi
essere liberata, quando non più necessaria, con \func{acl\_free}. Se
nell'argomento \param{len\_p} si passa un valore puntatore ad una variabile
-intera in questa verrà restituita la dimensione della stringa con la
-rappresentazione testuale (non comprendente il carattere nullo finale).
+intera in questa verrà restituita (come \itindex{value~result~argument}
+\textit{value result argument}) la dimensione della stringa con la
+rappresentazione testuale, non comprendente il carattere nullo finale.
La seconda funzione, \funcd{acl\_to\_any\_text}, permette di controllare con
dovizia di dettagli la generazione della stringa contenente la
questa funzione è una estensione specifica di Linux, e non è presente nella
bozza dello standard POSIX.1e.
-Per quanto utile per la visualizzazione o l'impostazione da comando delle ACL,
-la forma testuale non è la più efficiente per poter memorizzare i dati
-relativi ad una ACL, ad esempio quando si vuole eseguirne una copia a scopo di
-archiviazione. Per questo è stata prevista la possibilità di utilizzare una
-rappresentazione delle ACL in una apposita forma binaria contigua e
-persistente. È così possibile copiare il valore di una ACL in un buffer e da
-questa rappresentazione tornare indietro e generare una ACL.
+Per quanto utile per la visualizzazione o l'impostazione da riga di comando
+delle ACL, la forma testuale non è la più efficiente per poter memorizzare i
+dati relativi ad una ACL, ad esempio quando si vuole eseguirne una copia a
+scopo di archiviazione. Per questo è stata prevista la possibilità di
+utilizzare una rappresentazione delle ACL in una apposita forma binaria
+contigua e persistente. È così possibile copiare il valore di una ACL in un
+buffer e da questa rappresentazione tornare indietro e generare una ACL.
Lo standard POSIX.1e prevede a tale scopo tre funzioni, la prima e più
semplice è \funcd{acl\_size}, che consente di ottenere la dimensione che avrà
la citata rappresentazione binaria, in modo da poter allocare per essa un
buffer di dimensione sufficiente, il suo prototipo è:
-
\begin{funcproto}{
\fhead{sys/types.h}
\fhead{sys/acl.h}
}
\end{funcproto}
-
Prima di effettuare la lettura della rappresentazione binaria è sempre
necessario allocare un buffer di dimensione sufficiente a contenerla, pertanto
prima si dovrà far ricorso a \funcd{acl\_size} per ottenere tale dimensione e
poi allocare il buffer con una delle funzioni di
sez.~\ref{sec:proc_mem_alloc}. Una volta terminato l'uso della
-rappresentazione binaria, il buffer dovrà essere esplicitamente disallocato.
+rappresentazione binaria, il buffer dovrà essere esplicitamente disallocato,
+in questo caso con \func{free}.
La funzione che consente di leggere la rappresentazione binaria di una ACL è
\funcd{acl\_copy\_ext}, il cui prototipo è:
Viceversa se si vuole ripristinare una ACL a partire dalla rappresentazione
binaria della stessa disponibile in un buffer si potrà usare la funzione
\funcd{acl\_copy\_int}, il cui prototipo è:
-\begin{functions}
- \headdecl{sys/types.h}
- \headdecl{sys/acl.h}
-
- \funcdecl{ssize\_t acl\_copy\_int(const void *buf\_p)}
- Ripristina la rappresentazione binaria di una ACL.
+\begin{funcproto}{
+\fhead{sys/types.h}
+\fhead{sys/acl.h}
+\fdecl{acl\_t acl\_copy\_int(const void *buf\_p)}
+\fdesc{.}
+}
- \bodydesc{La funzione restituisce un oggetto di tipo \type{acl\_t} in caso
- di successo e \code{(acl\_t)NULL} in caso di errore, nel qual caso
- \var{errno} assumerà uno dei valori:
+{La funzione ritorna un oggetto di tipo \type{acl\_t} in caso di successo e
+ \val{NULL} per un errore, nel qual caso \var{errno} assumerà uno dei valori:
\begin{errlist}
\item[\errcode{EINVAL}] il buffer all'indirizzo \param{buf\_p} non contiene
una rappresentazione corretta di una ACL.
\item[\errcode{ENOMEM}] non c'è memoria sufficiente per allocare un oggetto
\type{acl\_t} per la ACL richiesta.
\end{errlist}
-
}
-\end{functions}
+\end{funcproto}
La funzione in caso di successo alloca autonomamente un oggetto di tipo
\type{acl\_t} che viene restituito come valore di ritorno con il contenuto
su un file o una directory. Per impostare una ACL sono disponibili due
funzioni; la prima è \funcd{acl\_set\_file}, che opera sia su file che su
directory, ed il cui prototipo è:
-\begin{functions}
- \headdecl{sys/types.h}
- \headdecl{sys/acl.h}
-
- \funcdecl{int acl\_set\_file(const char *path, acl\_type\_t type, acl\_t
- acl)}
- Imposta una ACL su un file o una directory.
+\begin{funcproto}{
+\fhead{sys/types.}
+\fhead{sys/acl.h}
+\fdecl{int acl\_set\_file(const char *path, acl\_type\_t type, acl\_t acl)}
+\fdesc{Imposta una ACL su un file o una directory.}
+}
- \bodydesc{La funzione restituisce $0$ in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà uno dei valori:
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà uno dei valori:
\begin{errlist}
\item[\errcode{EACCES}] o un generico errore di accesso a \param{path} o il
valore di \param{type} specifica una ACL il cui tipo non può essere
assegnato a \param{path}.
\item[\errcode{EINVAL}] o \param{acl} non è una ACL valida, o \param{type}
- ha in valore non corretto.
+ ha un valore non corretto.
\item[\errcode{ENOSPC}] non c'è spazio disco sufficiente per contenere i
dati aggiuntivi della ACL.
\item[\errcode{ENOTSUP}] si è cercato di impostare una ACL su un file
contenuto in un filesystem che non supporta le ACL.
\end{errlist}
- ed inoltre \errval{ENOENT}, \errval{ENOTDIR}, \errval{ENAMETOOLONG},
- \errval{EROFS}, \errval{EPERM}.
-}
-\end{functions}
+ ed inoltre \errval{ENAMETOOLONG}, \errval{ENOENT}, \errval{ENOTDIR},
+ \errval{EPERM}, \errval{EROFS} nel loro significato generico.}
+\end{funcproto}
La funzione consente di assegnare la ACL contenuta in \param{acl} al file o
alla directory indicate dal \textit{pathname} \param{path}, mentre
default, per i dettagli si ricorra alla pagina di manuale.} La seconda
funzione che consente di impostare una ACL è \funcd{acl\_set\_fd}, ed il suo
prototipo è:
-\begin{functions}
- \headdecl{sys/types.h}
- \headdecl{sys/acl.h}
-
- \funcdecl{int acl\_set\_fd(int fd, acl\_t acl)}
- Imposta una ACL su un file descriptor.
+\begin{funcproto}{
+\fhead{sys/types.h}
+\fhead{sys/acl.h}
+\fdecl{int acl\_set\_fd(int fd, acl\_t acl)}
+\fdesc{Imposta una ACL su un file descriptor.}
+}
- \bodydesc{La funzione restituisce $0$ in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà uno dei valori:
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà uno dei valori:
\begin{errlist}
- \item[\errcode{EINVAL}] o \param{acl} non è una ACL valida, o \param{type}
- ha in valore non corretto.
+ \item[\errcode{EINVAL}] o \param{acl} non è una ACL valida, o ha più voci di
+ quante se ne possono assegnare al file indicato da \param{fd}.
\item[\errcode{ENOSPC}] non c'è spazio disco sufficiente per contenere i
dati aggiuntivi della ACL.
\item[\errcode{ENOTSUP}] si è cercato di impostare una ACL su un file
contenuto in un filesystem che non supporta le ACL.
\end{errlist}
- ed inoltre \errval{EBADF}, \errval{EROFS}, \errval{EPERM}.
+ ed inoltre \errval{EBADF}, \errval{EPERM}, \errval{EROFS} nel loro
+ significato generico.
}
-\end{functions}
+\end{funcproto}
La funzione è del tutto è analoga a \funcd{acl\_set\_file} ma opera
esclusivamente sui file identificati tramite un file descriptor. Non dovendo
funzioni però sono alquanto macchinose da utilizzare per cui è molto più
semplice operare direttamente sulla rappresentazione testuale. Questo è il
motivo per non tratteremo nei dettagli dette funzioni, fornendone solo una
-descrizione sommaria; chi fosse interessato potrà ricorrere alle pagina di
+descrizione sommaria; chi fosse interessato potrà ricorrere alle pagine di
manuale.
Se si vuole operare direttamente sui contenuti di un oggetto di tipo
\type{acl\_t} infatti occorre fare riferimento alle singole voci tramite gli
opportuni puntatori di tipo \type{acl\_entry\_t}, che possono essere ottenuti
-dalla funzione \funcd{acl\_get\_entry} (per una voce esistente) o dalla
-funzione \funcd{acl\_create\_entry} per una voce da aggiungere. Nel caso della
+dalla funzione \funcm{acl\_get\_entry} (per una voce esistente) o dalla
+funzione \funcm{acl\_create\_entry} per una voce da aggiungere. Nel caso della
prima funzione si potrà poi ripetere la lettura per ottenere i puntatori alle
singole voci successive alla prima.
Una volta ottenuti detti puntatori si potrà operare sui contenuti delle singole
-voci; con le funzioni \funcd{acl\_get\_tag\_type}, \funcd{acl\_get\_qualifier},
-\funcd{acl\_get\_permset} si potranno leggere rispettivamente tipo,
+voci; con le funzioni \funcm{acl\_get\_tag\_type}, \funcm{acl\_get\_qualifier},
+\funcm{acl\_get\_permset} si potranno leggere rispettivamente tipo,
qualificatore e permessi mentre con le corrispondente funzioni
-\funcd{acl\_set\_tag\_type}, \funcd{acl\_set\_qualifier},
-\funcd{acl\_set\_permset} si possono impostare i valori; in entrambi i casi
+\funcm{acl\_set\_tag\_type}, \funcm{acl\_set\_qualifier},
+\funcm{acl\_set\_permset} si possono impostare i valori; in entrambi i casi
vengono utilizzati tipi di dato ad hoc.\footnote{descritti nelle singole
pagine di manuale.} Si possono poi copiare i valori di una voce da una ACL
-ad un altra con \funcd{acl\_copy\_entry} o eliminare una voce da una ACL con
-\funcd{acl\_delete\_entry}.
+ad un altra con \funcm{acl\_copy\_entry} o eliminare una voce da una ACL con
+\funcm{acl\_delete\_entry}.
\itindend{Access~Control~List~(ACL)}
spazio disco (i blocchi) che il numero di file (gli \itindex{inode}
\textit{inode}) e devono pertanto essere specificati per entrambe le risorse.
-La funzione che consente di controllare tutti i vari aspetti della gestione
-delle quote è \funcd{quotactl}, ed il suo prototipo è:
-\begin{functions}
- \headdecl{sys/types.h}
- \headdecl{sys/quota.h}
-
- \funcdecl{quotactl(int cmd, const char *dev, int id, caddr\_t addr)}
+La funzione di sistema che consente di controllare tutti i vari aspetti della
+gestione delle quote è \funcd{quotactl}, ed il suo prototipo è:
- Esegue una operazione di controllo sulle quote disco.
+\begin{funcproto}{
+\fhead{sys/types.h}
+\fhead{sys/quota.h}
+\fdecl{int quotactl(int cmd, const char *dev, int id, caddr\_t addr)}
+\fdesc{Esegue una operazione di controllo sulle quote disco.}
+}
- \bodydesc{La funzione restituisce $0$ in caso di successo e $-1$ in caso di
- errore, nel qual caso \var{errno} assumerà uno dei valori:
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà uno dei valori:
\begin{errlist}
\item[\errcode{EACCES}] il file delle quote non è un file ordinario.
- \item[\errcode{EBUSY}] si è richiesto \const{Q\_QUOTAON} ma le quote sono
+ \item[\errcode{EBUSY}] si è richiesto \const{Q\_QUOTAON}, ma le quote sono
già attive.
\item[\errcode{EFAULT}] l'indirizzo \param{addr} non è valido.
\item[\errcode{EIO}] errore di lettura/scrittura sul file delle quote.
superato il limite sul numero di file aperti nel sistema.
\item[\errcode{EINVAL}] o \param{cmd} non è un comando valido,
o il dispositivo \param{dev} non esiste.
- \item[\errcode{ENODEV}] \param{dev} non corrisponde ad un \textit{mount
- point} attivo.
+ \item[\errcode{ENODEV}] \param{dev} non corrisponde ad un
+ \itindex{mount~point} \textit{mount point} attivo.
\item[\errcode{ENOPKG}] il kernel è stato compilato senza supporto per le
quote.
\item[\errcode{ENOTBLK}] \param{dev} non è un dispositivo a blocchi.
filesystem senza quote attivate.
\end{errlist}
}
-\end{functions}
+\end{funcproto}
La funzione richiede che il filesystem sul quale si vuole operare sia montato
con il supporto delle quote abilitato; esso deve essere specificato con il
Il tipo di operazione che si intende effettuare deve essere indicato tramite
il primo argomento \param{cmd}, questo in genere viene specificato con
l'ausilio della macro \macro{QCMD}:
-\begin{functions}
- \funcdecl{int QCMD(subcmd,type)} Imposta il comando \param{subcmd} per il
- tipo di quote (utente o gruppo) \param{type}.
-\end{functions}
+
+{\centering
+\vspace{3pt}
+\begin{funcbox}{
+\fhead{sys/quota.h}
+\fdecl{int \macro{QCMD}(subcmd,type)}
+\fdesc{Imposta il comando \param{subcmd} per il tipo di quote (utente o
+ gruppo) \param{type}.}
+}
+\end{funcbox}
+}
+
\noindent che consente di specificare, oltre al tipo di operazione, se questa
deve applicarsi alle quote utente o alle quote gruppo, nel qual
caso \param{type} deve essere rispettivamente \const{USRQUOTA} o
\texttt{kernel\_cap\_t}; questo era, fino al kernel 2.6.25 definito come
intero a 32 bit per un massimo di 32 \textit{capabilities} distinte,
attualmente è stato aggiornato ad un vettore in grado di mantenerne fino a
- 64.} in cui ciascun bit corrisponde ad una capacità diversa.
+ 64.} in cui ciascun bit corrisponde ad una capacità diversa.
L'utilizzo di tre distinti insiemi serve a fornire una interfaccia flessibile
per l'uso delle \textit{capabilities}, con scopi analoghi a quelli per cui
tre insiemi illustrati in precedenza. Queste due funzioni sono \funcd{capget}
e \funcd{capset} e costituiscono l'interfaccia di gestione basso livello; i
loro rispettivi prototipi sono:
-\begin{functions}
- \headdecl{sys/capability.h}
- \funcdecl{int capget(cap\_user\_header\_t hdrp, cap\_user\_data\_t datap)}
- Legge le \textit{capabilities}.
-
- \funcdecl{int capset(cap\_user\_header\_t hdrp, const cap\_user\_data\_t
- datap)}
- Imposta le \textit{capabilities}.
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int capget(cap\_user\_header\_t hdrp, cap\_user\_data\_t datap)}
+\fdesc{Legge le \textit{capabilities}.}
+\fdecl{int capset(cap\_user\_header\_t hdrp, const cap\_user\_data\_t datap)}
+\fdesc{Imposta le \textit{capabilities}.}
+}
-
- \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}
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà uno dei 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
\textit{capability} di un altro processo senza avare
\const{CAP\_SETPCAP}.
\end{errlist}
- ed inoltre \errval{EFAULT} ed \errval{EINVAL}.
-}
-\end{functions}
+ ed inoltre \errval{EFAULT} ed \errval{EINVAL}
+ nel loro significato generico.}
+\end{funcproto}
+
Queste due funzioni prendono come argomenti due tipi di dati dedicati,
definiti come puntatori a due strutture specifiche di Linux, illustrate in
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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{cap\_t cap\_init(void)}
+\fdesc{Crea ed inizializza un \textit{capability state}.}
+}
+
+{La funzione ritorna un valore non nullo in caso di successo e\val{NULL} per
+ un errore, nel qual caso \var{errno} potrà assumere solo il valore
+ \errval{ENOMEM}.
+}
+\end{funcproto}
La funzione restituisce il puntatore \type{cap\_t} ad uno stato inizializzato
con tutte le \textit{capabilities} azzerate. In caso di errore (cioè quando
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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int cap\_free(void *obj\_d)}
+\fdesc{Disalloca la memoria allocata per i dati delle \textit{capabilities}..}
+}
+
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} potrà assumere solo il valore \errval{EINVAL}.
+}
+\end{funcproto}
+
La funzione permette di liberare la memoria allocata dalle altre funzioni
della libreria sia per un \textit{capability state}, nel qual caso l'argomento
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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{cap\_t cap\_dup(cap\_t cap\_p)}
+\fdesc{Duplica un \textit{capability state} restituendone una copia.}
+}
+
+{La funzione ritorna un valore non nullo in caso di successo e \val{NULL} per
+ un errore, nel qual caso \var{errno} assumerà valori \errval{ENOMEM} o
+ \errval{EINVAL} nel loro significato generico.}
+\end{funcproto}
+
La funzione crea una copia del \textit{capability state} posto all'indirizzo
\param{cap\_p} che si è passato come argomento, restituendo il puntatore alla
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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int cap\_clear(cap\_t cap\_p)}
+\fdesc{Inizializza un \textit{capability state} cancellando tutte le
+ \textit{capabilities}.}
+}
+
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} potrà assumere solo il valore \errval{EINVAL}.
+}
+\end{funcproto}
La funzione si limita ad azzerare tutte le \textit{capabilities} presenti nel
\textit{capability state} all'indirizzo \param{cap\_p} passato come argomento,
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)}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int cap\_clear\_flag(cap\_t cap\_p, cap\_flag\_t flag)}
+\fdesc{ncella dal \textit{capability state} \param{cap\_p} tutte le
+ \textit{capabilities} dell'insieme \param{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 ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} potrà assumere solo il valore \errval{EINVAL}.
+}
+\end{funcproto}
La funzione richiede che si indichi quale degli insiemi si intente cancellare
con l'argomento \param{flag}. Questo deve essere specificato con una variabile
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
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int cap\_compare(cap\_t cap\_a, cap\_t cap\_b)}
+\fdesc{Confronta due \textit{capability state}.}
+}
+
+{La funzione ritorna $0$ se i \textit{capability state} sono identici
ed un valore positivo se differiscono, non sono previsti errori.}
-\end{functions}
+\end{funcproto}
+
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
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}
+
+{\centering
+\vspace{3pt}
+\begin{funcbox}{
+\fhead{sys/capability.h}
+\fdecl{int \macro{CAP\_DIFFERS}(value, flag)}
+\fdesc{Controlla lo stato di eventuali differenze delle \textit{capabilities}
+ nell'insieme \texttt{flag}.}
+}
+\end{funcbox}
+}
La macro che richiede si passi nell'argomento \texttt{value} il risultato
della funzione \func{cap\_compare} e in \texttt{flag} l'indicazione (coi
\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
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{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}.
+\fdesc{Legge il valore di una \textit{capability}.}
+\fdecl{int cap\_set\_flag(cap\_t cap\_p, cap\_flag\_t flag, int ncap,
+ cap\_value\_t *caps, cap\_flag\_value\_t value)}
+\fdesc{Imposta 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}.
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} potrà assumere solo il valore \errval{EINVAL}.
}
-\end{functions}
+\end{funcproto}
In entrambe le funzioni l'argomento \param{cap\_p} indica il puntatore al
\textit{capability state} su cui operare, mentre l'argomento \param{flag}
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)}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{char * cap\_to\_text(cap\_t caps, ssize\_t * length\_p)}
+\fdesc{Genera una visualizzazione testuale delle \textit{capabilities}.}
+}
- 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 un puntatore alla stringa con la descrizione delle
+ \textit{capabilities} in caso di successo e \val{NULL} per un errore, nel
+ qual caso \var{errno} assumerà i valori \errval{EINVAL} o \errval{ENOMEM}
+ nel loro significato generico.}
+\end{funcproto}
La funzione ritorna l'indirizzo di una stringa contente la descrizione
testuale del contenuto del \textit{capability state} \param{caps} passato come
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)}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{cap\_t cap\_from\_text(const char *string)}
+\fdesc{Crea un \textit{capability state} dalla sua rappresentazione testuale.}
+}
- Crea un \textit{capability state} dalla sua rappresentazione testuale.
+{La funzione ritorna un puntatore valid in caso di successo e \val{NULL} per
+ un errore, nel qual caso \var{errno} assumerà i valori \errval{EINVAL} o
+ \errval{ENOMEM} nel loro significato generico.}
+\end{funcproto}
- \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
stringhe usate nelle rispettive rappresentazioni e viceversa. Le due funzioni,
\funcd{cap\_to\_name} e \funcd{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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{char * cap\_to\_name(cap\_value\_t cap)}
+\fdecl{int cap\_from\_name(const char *name, cap\_value\_t *cap\_p)}
+
+\fdesc{Convertono le \textit{capabilities} dalle costanti alla rappresentazione
+ testuale e viceversa.}
+}
+
+{La funzione \func{cap\_to\_name} ritorna un puntatore ad una stringa in caso
+ di successo e \val{NULL} per un errore, mentre \func{cap\_to\_name} ritorna
+ $0$ in caso di successo e $-1$ nel qual caso di errore, per entrambe
+ \var{errno}può assumere i valori \errval{EINVAL} o \errval{ENOMEM}.
+}
+\end{funcproto}
La prima funzione restituisce la stringa (allocata automaticamente e che dovrà
essere liberata con \func{cap\_free}) che corrisponde al valore della
\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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{cap\_t cap\_get\_proc(void)}
+\fdesc{Legge le \textit{capabilities} del processo corrente.}
+}
+
+{La funzione ritorna un valore diverso da \val{NULL} in caso di successo e
+ \val{NULL} per un errore, nel qual caso \var{errno} assumerà i valori
+ \errval{EINVAL}, \errval{EPERM} o \errval{ENOMEM} nel loro significato
+ generico.}
+\end{funcproto}
La funzione legge il valore delle \textit{capabilities} associate al processo
da cui viene invocata, restituendo il risultato tramite il puntatore ad 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 \headfile{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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int capgetp(pid\_t pid, cap\_t cap\_d)}
+\fdesc{Legge le \textit{capabilities} di un processo.}
+}
+
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà i valori \errval{EINVAL}, \errval{EPERM} o
+ \errval{ENOMEM} nel loro significato generico.}
+\end{funcproto}
+
%TODO controllare e correggere i codici di errore!!!
La funzione legge il valore delle \textit{capabilities} del processo indicato
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}
+\begin{funcproto}{
+\fhead{sys/capability.h}
+\fdecl{int cap\_set\_proc(cap\_t cap\_p)}
+\fdesc{Imposta le \textit{capabilities} del processo corrente.}
+}
+
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà i valori \errval{EINVAL}, \errval{EPERM} o
+ \errval{ENOMEM} nel loro significato generico.}
+\end{funcproto}
La funzione modifica le \textit{capabilities} del processo corrente secondo
quanto specificato con l'argomento \param{cap\_p}, posto che questo sia