NAME

afsperlacl - ACL functions

SYNOPIS

  use AFS;              # import all AFS names
  use AFS @AFS::ACL;    # import just the ACL names

  AFS::ACL::new
  ascii2rights
  cleanacl
  copyacl
  crights 
  getacl
  modifyacl
  newacl
  rights2ascii
  setacl

  $acl -> empty;
  $acl -> addacl
  $acl -> clear 
  $acl -> copy;
  $acl -> exists
  $acl -> get
  $acl -> keys 
  $acl -> length
  $acl -> remove
  $acl -> set
  $acl -> nclear 
  $acl -> nexists
  $acl -> nget
  $acl -> nkeys 
  $acl -> nlength
  $acl -> nremove
  $acl -> nset

DESCRIPTION

This document describes the ACL related functions available in the AFS module.

$acl = AFS::ACL::new([\%pos [, \%neg]]);

$acl = newacl([\%pos [, \%neg]]);

 Used to create an ACL object. The second form is exported by the AFS
 module and is therefore a little easier to use.

 Examples:
 
    $acl = newacl({"schemers"=>crights("all"), "system:anyuser"=>"l"});
    $acl = newacl({"schemers"=>"rl"}, {"rjs"=>"l"});

$acl->copy;

 Returns a copy of an existing ACL. 

    $newacl = $acl->copy;

 Changes made to $newacl do not change $acl. 

$acl ->addacl($newacl);

 Adds all the ACL entries in $newacl to $acl. 

$acl ->empty;

 Removes all positive and negative entries from an ACL.

$acl->keys

 Returns all the keys (PTS names) from the positive ACL hash.

$acl->length

 Returns the length (number of keys) in the postive ACL hash.

$acl->get($key)

 Returns the access rights for the given key in the positive ACL hash.

$acl->exists($key)

 Returns 1 if the given key exists in the positive ACL hash.

$acl->set($key, $rights);

 Adds the given key and access rights to the positive ACL hash.

$acl->remove($key)

 Removes the given key from the positive ACL hash.

$acl->clear

 Removes all positive entries from the ACL.

$acl->nkeys

$acl->nlength

$acl->nget($key)

$acl->nexists($key)

$acl->nset($key, $rights);

$acl->nremove($key)

$acl->nclear

 Same as above but work on the negative ACL hash instead of the positive.

$acl = getacl($path [,$follow=1]);

  Retrieves the ACL for the given path. 

  For example:

    $acl = getacl("/afs/ir.stanford.edu");

$ok = setacl($path, $acl [,$follow=1]);

  Sets the ACL for the given path. This call replaces the existing ACL
  value with the new ACLs.

$ok = modifyacl($path, $acl [,$follow=1])

  Sets the ACL to the union of the given ACL and the current ACL.
  An access right of "none" or "" will cause an entry to be removed from 
  the ACL. 
  
  Example: 

     $ok = modifyacl($path,newacl({"schemers" => "none"}));
     
  Will remove "schemers" from the ACL on $path. Since this function does
  a union on both hash tables it is not an error if "schemers" is not
  on the existing ACl.

$ok = copyacl($from_path, $to_path [,$follow=1]);

  Copies the ACL on $from_path to $to_path.

$ok = cleanacl($path [,$follow=1]);

  Removes any "orphan" ids on an ACL. An orphan id is an ID that
  corresponds to an ID that is longer in the PTS database. Orphan
  ids are also removed during a setacl or modifyacl call.

$flags = ascii2rights($rights);

  Returns -1 if $rights are not valid (rlidwka, read, write, all, none).
  or returns the internal value (int32 with flags set).

$print = rights2ascii($flags);

  Converts $internal_value to ascii.

$crights = crights($rights);

  Canonicalize rights string. Recognizes the following "special" rights
  strings:

  read  => rl
  write => rlidwk
  all   => rlidwka
  mail  => lik

  Will also remove duplicate rights and "sort" the rights (rlidwka)

  $crights = crights("arkail");  # "rlika"