Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
setacl(2)		      System Calls Manual		     setacl(2)

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

       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, 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 deletes all	of a file's previous optional ACL  en-
       tries  (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
       completely define the file's ACL.

       As a special case, if nentries is negative (that	is, a  value  of  (de-
       fined  in  the acl parameter is ignored,	all of the file's optional en-
       tries, 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 See chmod(2).

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

	      applies to user
			     u in group	g
	      applies to user
			     u in any group
	      applies to any user in group
	      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 header file defines as the non-specific uid value and as  the  non-
       specific	gid value represented by above.	 If uid	in an entry is it is a
       entry.  If gid in an entry is it	is a entry.  If	both uid and  gid  are
       non-specific, the file's	entry is

       The  header  file defines meanings of mode bits in ACL entries (and Ir-
       relevant	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 changes the file's corresponding
       permission bits.	 The permission	bits can be altered also by using (see
       chmod(2)) and read using	(see stat(2)).

       The  number  of entries allowed per file	(see in	is small for space and
       performance reasons.  User groups should	be created as needed  for  ac-
       cess  control  purposes.	  Since	 ordinary  users cannot	create groups,
       their ability to	control	file access with ACLs might be	somewhat  lim-

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

       and fail	if any of the following	conditions are encountered:

	      [ENOTDIR]		  A  component of the path prefix is not a di-

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

	      [EBADF]		  fildes is not	a valid	file descriptor.

	      [EACCES]		  A component of the path prefix denies	search

	      [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

	      [EFAULT]		  path or acl points outside the allocated ad-
				  dress	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

	      [E2BIG]		  An attempt was made to set an	ACL with  more
				  than 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 bytes,	or the
				  length of a component	of path	exceeds	 bytes
				  while	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.

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

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

       and are not supported on	remote files.

       ACLs are	only supported on HFS file systems.

       and were	developed by HP.

       access(2),   chmod(2),	getaccess(2),	getacl(2),   stat(2),  acl(5),



Want to link to this manual page? Use this URL:

home | help