unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 setacl(2)							   setacl(2)




 NAME
      setacl, fsetacl - set access control list (ACL) information

 SYNOPSIS
      #include <&lt&lt&lt;sys/acl.h>&gt&gt&gt;

      int setacl(
	   const char *path,
	   int nentries,
	   const struct acl_entry *acl
      );

      int fsetacl(
	   int fildes,
	   int nentries,
	   const struct acl_entry *acl
      );

 DESCRIPTION
      setacl() sets an existing file's access control list (ACL) or deletes
      optional entries from it.	 path points to a path name of a file.

      Similarly, fsetacl() sets an existing file's access control list for
      an open file known by the file descriptor fildes.

      The effective user ID of the process must match the owner of the file
      or be the super-user to set a file's ACL.

      A successful call to setacl() deletes all of a file's previous
      optional ACL entries (see explanation below), if any.  nentries
      indicates how many valid entries are defined in the acl parameter.  If
      nentries is zero or greater, the new ACL is applied to the file.	If
      any of the file's base entries (see below) is not mentioned in the new
      ACL, it is retained but its access mode is set to zero (no access).
      Hence, routine calls of setacl() completely define the file's ACL.

      As a special case, if nentries is negative (that is, a value of
      ACL_DELOPT (defined in <&lt&lt&lt;sys/acl.h>&gt&gt&gt;), the acl parameter is ignored, all
      of the file's optional entries, if any, are deleted, and its base
      entries are left unaltered.

      Some of the miscellaneous mode bits in the file's mode might be turned
      off as a consequence of calling setacl().	 See chmod(2).

    Access Control Lists
      An ACL consists of a series of entries.  Entries can be categorized in
      four levels of specificity:

	   (u.g, mode)	  applies to user u in group g
	   (u.%, mode)	  applies to user u in any group




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 setacl(2)							   setacl(2)




	   (%.g, mode)	  applies to any user in group g
	   (%.%, mode)	  applies to any user in any group

      Entries in the ACL must be unique; no two entries can have the same
      user ID (uid) and group ID (gid) (see below).  Entries can appear in
      any order.  The system orders them as needed for access checking.

      The <&lt&lt&lt;sys/acl.h>&gt&gt&gt; header file defines ACL_NSUSER as the non-specific uid
      value and ACL_NSGROUP as the non-specific gid value represented by %
      above.  If uid in an entry is ACL_NSUSER, it is a %.g entry.  If gid
      in an entry is ACL_NSGROUP, it is a u.% entry.  If both uid and gid
      are non-specific, the file's entry is %.%.

      The <&lt&lt&lt;unistd.h>&gt&gt&gt; header file defines meanings of mode bits in ACL
      entries (R_OK, W_OK, and X_OK).  Irrelevant bits in mode values must
      be zero.

      Every file's ACL has three base entries which cannot be added or
      deleted, but only modified.  The base ACL entries are mapped directly
      from the file's permission bits.

	   (<file's owner> . ACL_NSGROUP, <file's owner mode bits>)
	   (ACL_NSUSER . <file's group>, <file's group mode bits>)
	   (ACL_NSUSER . ACL_NSGROUP, <file's other mode bits>)

      In addition, up to 13 optional ACL entries can be set to restrict or
      grant access to a file.

      Altering a base ACL entry's modes with setacl() changes the file's
      corresponding permission bits.  The permission bits can be altered
      also by using chmod() (see chmod(2)) and read using stat() (see
      stat(2)).

      The number of entries allowed per file (see NACLENTRIES in
      <&lt&lt&lt;sys/acl.h>&gt&gt&gt;) is small for space and performance reasons.	User groups
      should be created as needed for access control purposes.	Since
      ordinary users cannot create groups, their ability to control file
      access with ACLs might be somewhat limited.

 RETURN VALUE
      Upon successful completion, setacl() and fsetacl() return a value of
      zero.  If an error occurs, they return -1, the file's ACL is not
      modified, and errno is set to indicate the error.

 ERRORS
      setacl() and fsetacl() fail if any of the following conditions are
      encountered:

	   [ENOTDIR]	       A component of the path prefix is not a
			       directory.




 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 setacl(2)							   setacl(2)




	   [ENOENT]	       The named file does not exist (for example,
			       path is null or a component of path does not
			       exist).

	   [EBADF]	       fildes is not a valid file descriptor.

	   [EACCES]	       A component of the path prefix denies search
			       permission.

	   [EPERM]	       The effective user ID does not match the
			       owner of the file and the effective user ID
			       is not super-user.

	   [EROFS]	       The named file resides on a read-only file
			       system.

	   [EFAULT]	       path or acl points outside the allocated
			       address space of the process, or acl is not
			       as large as indicated by nentries.

	   [EINVAL]	       There is a redundant entry in the ACL, or acl
			       contains an invalid uid, gid, or mode value.

	   [E2BIG]	       An attempt was made to set an ACL with more
			       than NACLENTRIES entries.

	   [EOPNOTSUPP]	       The function is not supported on remote files
			       by some networking services.

	   [ENOSYS]	       The function is not supported by this file
			       system type.

	   [ENOSPC]	       Not enough space on the file system.

	   [ENFILE]	       System file table is full.

	   [ENAMETOOLONG]      The length of path exceeds PATH_MAX bytes, or
			       the length of a component of path exceeds
			       NAME_MAX bytes while _POSIX_NO_TRUNC is in
			       effect.

	   [ELOOP]	       Too many symbolic links were encountered in
			       translating the path name.

	   [EDQUOT]	       User's disk quota block or inode limit has
			       been reached for this file system.

 EXAMPLES
      The following code fragment defines and sets an ACL on file ../shared
      which allows the file's owner to read, write, and execute or search
      the file, and allows user 103, group 204 to read the file.



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 setacl(2)							   setacl(2)




	   #include <&lt&lt&lt;unistd.h>&gt&gt&gt;
	   #include <&lt&lt&lt;sys/stat.h>&gt&gt&gt;
	   #include <&lt&lt&lt;sys/acl.h>&gt&gt&gt;

	   char *filename = "../shared";
	   struct acl_entry acl [2];
	   struct stat statbuf;

	   if (stat (filename, &&amp&amp&amp; statbuf) <&lt&lt&lt; 0)
	       error (...);

	   acl [0] . uid  = statbuf . st_uid;	/* file owner */
	   acl [0] . gid  = ACL_NSGROUP;
	   acl [0] . mode = R_OK | W_OK | X_OK;

	   acl [1] . uid  = 103;
	   acl [1] . gid  = 204;
	   acl [1] . mode = R_OK;

	   if (setacl (filename, 2, acl))
		error (...);

      The following call deletes all optional ACL entries from file1:
	   setacl ("file1", ACL_DELOPT, (struct acl_entry *) 0);

 DEPENDENCIES
    NFS
      setacl() and fsetacl() are not supported on remote files.

    HFS
      ACLs are only supported on HFS file systems.

 AUTHOR
      setacl() and fsetacl() were developed by HP.

 SEE ALSO
      access(2), chmod(2), getaccess(2), getacl(2), stat(2), acl(5),
      unistd(5).
















 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000