acl(2)

NAME

     acl, facl - get or set a file's Access Control List (ACL)

SYNOPSIS

     #include <sys/acl.h>

     int  acl(char  *pathp,  int  cmd,  int  nentries,   aclent_t
     *aclbufp);

     int  facl(int  fildes,  int  cmd,  int  nentries,   aclent_t
     *aclbufp);

DESCRIPTION

     The acl() and facl() functions get or set the  ACL of a file
     whose  name is given by pathp or referenced by the open file
     descriptor fildes. The nentries argument specifies how many
      ACL entries fit into buffer aclbufp. The acl() function  is
     used to manipulate  ACL on file system objects.

     The following values for cmd are supported:

     SETACL
           nentries ACL entries, specified in buffer aclbufp, are
           stored in the file's  ACL. All directories in the path
           name must be searchable.

     GETACL
           Buffer aclbufp is filled with the file's  ACL entries.
           Read  access  to  the  file  is  not required, but all
           directories in the path name must be searchable.

     GETACLCNT
           The number of entries in the file's  ACL is  returned.
           Read  access  to  the  file  is  not required, but all
           directories in the path name must be searchable.

RETURN VALUES

     Upon successful completion,  acl() and facl()  return  0  if
     cmd  is  SETACL. If cmd is  GETACL or  GETACLCNT, the number
     of  ACL entries is returned. Otherwise, -1 is  returned  and
     errno is set to indicate the error.

ERRORS

     The acl() function will fail if:

     EACCESS
           The caller does not have access to a component of  the
           pathname.

     EFAULT
           The pathp or aclbufp argument  points  to  an  illegal
           address.

     EINVAL
           The  cmd  argument  is   not    GETACL,   SETACL,   or
           GETACLCNT;  the  cmd argument is  SETACL and  nentries
           is less than 3; or the cmd argument is  SETACL and the
           ACL specified in  aclbufp is not valid.

     EIO   A disk  I/O   error  has  occurred  while  storing  or
           retrieving the  ACL.

     ENOENT
           A component of the path does not exist.

     ENOSPC
           The cmd argument is  GETACL and nentries is less  than
           the  number  of entries in the file's  ACL, or the cmd
           argument is  SETACL and there is insufficient space in
           the file system to store the  ACL.

     ENOTDIR
           A component of the path specified by pathp  is  not  a
           directory,  or  the  cmd  argument  is   SETACL and an
           attempt is made to set a default  ACL on a  file  type
           other than a directory.

     ENOSYS
           The cmd argument is  SETACL and the file specified  by
           pathp  resides  on a file system that does not support
           ACLs, or the acl() function is not supported  by  this
           implementation.

     EPERM The effective user ID does not match the owner of  the
           file   and  the  process  does  not  have  appropriate
           privilege.

     EROFS The cmd argument is  SETACL and the file specified  by
           pathp  resides  on a file system that is mounted read-
           only.

USAGE

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE  TYPE       |       ATTRIBUTE  VALUE      |
    |_____________________________|_____________________________|
    | Interface  Stability        | Evolving                    |
    |_____________________________|_____________________________|

SEE ALSO

     getfacl(1),   setfacl(1),   mount_ufs(1M),   aclcheck(3SEC),
     aclsort(3SEC)