Copyright	© 2013-2014 Nicola Squartini
License	BSD3
Maintainer	Nicola Squartini <tensor5@gmail.com>
Stability	experimental
Portability	portable
Safe Haskell	Trustworthy
Language	Haskell2010

System.Posix.ACL.C

Contents

ACL initialization
ACL entry manipulation
Get, set and delete ACLs from a file
ACL format translation

Description

Functions in this module are bindings to the C API defined in IEEE Std 1003.1e. The design goal is to be as low level as possible without having to allocate or deallocate memory, and remaining type-safe. In order to reach this goal, all pointers to opaque C structures are represented by monad transformers representing actions on those pointers. Here is the pointer to monad transformer correspondence:

acl_t         <--> AclT
acl_entry_t   <--> EntryT
acl_permset_t <--> PermsetT

A common usage pattern is to modify the permset of an entry inside an ACL. This is done in three steps:

convert the PermsetT m a modification of permset into an EntryT m a modification of entry;
convert the EntryT m a into an AclT m a modification of ACL;
execute the AclT m a in the base monad m.

For example in

fromText "u::rw,g::r,o::r" $ getEntry 0 $ changePermset $ addPerm Execute

addPerm Execute is the PermsetT that adds the execute permission, changePermset converts PermsetT into EntryT, getEntry 0 modifies the 1st entry of the ACL according to the action contained in EntryT (thus converts EntryT into AclT), and finally fromText "u::rw,g::r,o::r" runs the AclT action on the ACL represented by the short text form u::rw,g::r,o::r. In words, it adds execute permission to the 1st entry of u::rw,g::r,o::r, producing u::rwx,g::r,o::r.

Synopsis

ACL initialization

data AclT m a Source

Action to be performed on an ACL. The action contained in the transformer AclT can be executed in the base monad using one of the functions newACL, getFdACL, getFileACL, fromExt or fromText.

Instances

MonadTrans AclT
MonadTransControl AclT
MonadBase b m => MonadBase b (AclT m)
MonadBaseControl b m => MonadBaseControl b (AclT m)
Alternative m => Alternative (AclT m)
Monad m => Monad (AclT m)
Functor m => Functor (AclT m)
MonadFix m => MonadFix (AclT m)
MonadPlus m => MonadPlus (AclT m)
Applicative m => Applicative (AclT m)
MonadIO m => MonadIO (AclT m)
data StT AclT = StAcl { unStAcl :: StT (ReaderT (Ptr AclT)) a }
data StM (AclT m) = StMAcl { unStMAcl :: ComposeSt AclT m a }

newACL :: MonadBaseControl IO m => Int -> AclT m a -> m a Source

Run the given action on a newly created ACL with enough preallocated memory to hold n entries. Use createEntry to create entries in the preallocated memory.

Call to acl_init().

dupACL Source

Arguments

:: MonadBaseControl IO m
=> AclT m a	action to be run on the duplicate
-> AclT m a

Create a copy of the current ACL and run the given action on the duplicate. For example

fromText "u::rw,g::r,o::r" $ dupACL (calcMask >> toText >>= lift . print) >> toText >>= lift . print

copies the ACL represented by u::rw,g::r,o::r to a new ACL, calculates and sets the permissions of Mask (see calcMask) in the newly created ACL and prints out the result. It also prints out the original ACL.

Call to acl_dup().

ACL entry manipulation

data EntryT m a Source

Action to be performed on an ACL entry. In order to execute the action contained in the EntryT transformer in the base monad, EntryT must first be converted into AclT using one of the functions createEntry, getEntries or getEntry.

Instances

MonadTrans EntryT
MonadTransControl EntryT
MonadBase b m => MonadBase b (EntryT m)
MonadBaseControl b m => MonadBaseControl b (EntryT m)
Alternative m => Alternative (EntryT m)
Monad m => Monad (EntryT m)
Functor m => Functor (EntryT m)
MonadFix m => MonadFix (EntryT m)
MonadPlus m => MonadPlus (EntryT m)
Applicative m => Applicative (EntryT m)
MonadIO m => MonadIO (EntryT m)
data StT EntryT = StEntry { unStEntry :: StT (ReaderT (AclEntryT, AclT)) a }
data StM (EntryT m) = StMEntry { unStMEntry :: ComposeSt EntryT m a }

createEntry :: MonadBase IO m => EntryT m a -> AclT m a Source

Create a new entry in the ACL an run the given action on it. If necessary, the ACL will allocate memory for the new entry.

Call to acl_create_entry().

getEntries :: MonadBase IO m => [EntryT m a] -> ListT (AclT m) a Source

Run the list of given actions on the list of entries of the ACL.

Warning: using setTag as one of the EntryTs of getEntries is not recommended, as it may rearrange the list of entries inside the ACL, yielding unexpected results.

Call to acl_get_entry().

getEntry :: MonadBase IO m => Int -> EntryT m a -> AclT m a Source

Run the given action on the n-th entry of the ACL (entry enumeration begins from 0).

Call to acl_get_entry().

copyEntry :: MonadBase IO m => EntryT (EntryT m) () Source

Copy the contents of an ACL entry to an existing ACL entry of a possibly different ACL. For example

fromText "u::rw,u:2:rwx,g::r,m:rwx,o::r" $ getEntry 1 $ fromText "u::rw,u:1:rw,u:8:rw,g::r,m:rwxo::r" (getEntry 2 copyEntry >> toText)

copies the 2nd entry of u::rw,u:2:rwx,g::r,m:rwx,o::r (namely u:2:rwx) into the 3rd entry of u::rw,u:1:rw,u:8:rw,g::r,m:rwxo::r (namely u:8:rw) and prints the result.

Call to acl_copy_entry().

deleteEntry :: MonadBase IO m => EntryT m () Source

Delete the entry.

Call to acl_delete_entry().

Warning: no further action should be performed on this entry.

valid :: MonadBase IO m => AclT m Bool Source

Run a validity check on the ACL (see acl_valid() in section 23.4.28 of IEEE Std 1003.1e).

Call to acl_valid().

data PermsetT m a Source

Action to be performed on the permission set of an ACL entry. In order to execute the action contained in the PermsetT transformer in the base monad, PermsetT must first be converted into EntryT using changePermset, and then into AclT.

Instances

MonadTrans PermsetT
MonadTransControl PermsetT
MonadBase b m => MonadBase b (PermsetT m)
MonadBaseControl b m => MonadBaseControl b (PermsetT m)
Alternative m => Alternative (PermsetT m)
Monad m => Monad (PermsetT m)
Functor m => Functor (PermsetT m)
MonadFix m => MonadFix (PermsetT m)
MonadPlus m => MonadPlus (PermsetT m)
Applicative m => Applicative (PermsetT m)
MonadIO m => MonadIO (PermsetT m)
data StT PermsetT = StPermset { unStPermset :: StT (ReaderT AclPermsetT) a }
data StM (PermsetT m) = StMPermset { unStMPermset :: ComposeSt PermsetT m a }

data Perm Source

A single permission.

Constructors

Read
Write
Execute

Instances

Eq Perm
Read Perm
Show Perm

changePermset :: MonadBase IO m => PermsetT m a -> EntryT m a Source

Change the permission set of the entry.

Call to acl_get_permset() and acl_set_permset().

addPerm :: MonadBase IO m => Perm -> PermsetT m () Source

Add a specific permission.

Call to acl_add_perm().

calcMask :: MonadBase IO m => AclT m () Source

Calculate and set the permissions associated with the Mask ACL entry of the ACL. The value of the new permissions is the union of the permissions granted by all entries of tag type Group, GroupObj, or User. If the ACL already contains a Mask entry, its permissions are overwritten; if it does not contain a Mask entry, one is added.

Call to acl_calc_mask().

clearPerms :: MonadBase IO m => PermsetT m () Source

Clear all permissions from the permission set.

Call to acl_clear_perms().

deletePerm :: MonadBase IO m => Perm -> PermsetT m () Source

Remove a specific permission.

Call to acl_delete_perm().

data Tag Source

Tag type and qualifier of an ACL.

Constructors