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

FreeBSD Manual Pages

  
 
  

home | help
chown(2)			 System	Calls			      chown(2)

NAME
       chown, lchown, fchown, fchownat - change	owner and group	of a file

SYNOPSIS
       #include	<unistd.h>
       #include	<sys/types.h>

       int chown(const char *path, uid_t owner,	gid_t group);

       int lchown(const	char *path, uid_t owner, gid_t group);

       int fchown(int fildes, uid_t owner, gid_t group);

       int  fchownat(int  fildes,  const char *path, uid_t owner, gid_t	group,
       int flag);

DESCRIPTION
       The chown() function sets the owner ID and group	ID of the file	speci-
       fied  by	path or	referenced by the open file descriptor fildes to owner
       and group respectively. If owner	or group is specified as  -1,  chown()
       does not	change the corresponding ID of the file.

       The  lchown() function sets the owner ID	and group ID of	the named file
       in the same manner as chown(), unless the  named	 file  is  a  symbolic
       link. In	this case, lchown() changes the	ownership of the symbolic link
       file itself, while chown() changes the ownership	of the file or	direc-
       tory to which the symbolic link refers.

       The  fchownat()	function  sets	the owner ID and group ID of the named
       file  in	the same manner	as chown(). If,	however, the path argument  is
       relative,  the  path is resolved	relative to the	fildes argument	rather
       than the	current	working	directory.  If the  fildes  argument  has  the
       special	value  FDCWD, the path path resolution reverts back to current
       working directory relative.  If the flag	argument is set	to SYMLNK, the
       function	 behaves  like lchown()	with respect to	symbolic links.	If the
       path argument is	absolute, the fildes argument is ignored.  If the path
       argument	is a null pointer, the function	behaves	like fchown().

       If   chown(), lchown(), fchown(), or fchownat() is invoked by a process
       that does not have {PRIV_FILE_SETID} asserted in	its effective set, the
       set-user-ID  and	set-group-ID bits of the file mode, S_ISUID and	 S_IS-
       GID respectively, are cleared (see  chmod(2)). Additional  restrictions
       apply when changing the ownership to uid	0.

       The  operating  system  defines several privileges to override restric-
       tions on	the chown() family of functions.  When	the  {PRIV_FILE_CHOWN}
       privilege  is  asserted	in  the	 effective set of the current process,
       there are no restrictions except	in the special circumstances of	chang-
       ing  ownership to or from uid 0.	When the {PRIV_FILE_CHOWN_SELF}	privi-
       lege is asserted, ownership changes are	restricted  to	the  files  of
       which  the  ownership  matches  the  effective  user  ID	of the current
       process.	 If neither privilege is asserted in the effective set of  the
       calling	process, ownership changes are limited to changes of the group
       of the file to the list of supplementary	group IDs  and	the  effective
       group ID.

       The operating system provides a configuration option, {_POSIX_CHOWN_RE-
       STRICTED}, to control the default behavior of processes and the	behav-
       ior  of the NFS server.	If {_POSIX_CHOWN_RESTRICTED} is	not in effect,
       the privilege {PRIV_FILE_CHOWN_SELF} is asserted	in the inheritable set
       of  all	processes unless overridden by policy.conf(4) or user_attr(4).
       To set  this  configuration  option,  include  the  following  line  in
       /etc/system:

	      set rstchown = 1

       To disable this option, include the following line in  /etc/system:

	      set rstchown = 0

       See system(4) and  fpathconf(2).

       Upon successful completion, chown(), fchown() and lchown() mark for up-
       date the	st_ctime field of the file.

RETURN VALUES
       Upon successful completion, 0 is	returned. Otherwise, -1	 is  returned,
       the  owner  and	group of the named file	remain unchanged, and errno is
       set to indicate the error.

ERRORS
       All of these functions will fail	if:

       EPERM	       The effective user ID does not match the	owner  of  the
		       file  and  the  {PRIV_FILE_CHOWN}  privilege is not as-
		       serted in the effective set of the calling process,  or
		       the {PRIV_FILE_CHOWN_SELF} privilege is not asserted in
		       the effective set of the	calling	process.

       The chown(), lchown(), and fchownat() functions will fail if:

       EACCES	       Search permission is denied on a	component of the  path
		       prefix of path.

       EFAULT	       The  path argument points to an illegal address and for
		       fchownat(), the file descriptor has the value AT_FDCWD.

       EINTR	       A signal	was caught during the execution	of the chown()
		       or lchown() function.

       EINVAL	       The group or owner argument is out of range.

       EIO	       An  I/O error occurred while reading from or writing to
		       the file	system.

       ELOOP	       Too many	symbolic links were encountered	in translating
		       path.

       ENAMETOOLONG    The  length of the path argument	exceeds	{PATH_MAX}, or
		       the length of a path component exceeds {NAME_MAX} while
		       {_POSIX_NO_TRUNC} is in effect.

       ENOLINK	       The  path  argument  points to a	remote machine and the
		       link to that machine is no longer active.

       ENOENT	       Either a	component of the path prefix or	the  file  re-
		       ferred to by path does not exist	or is a	null pathname.

       ENOTDIR	       A  component of the path	prefix of path is not a	direc-
		       tory, or	the path supplied to  fchownat()  is  relative
		       and  the	 file  descriptor provided does	not refer to a
		       valid directory.

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

       The fchown() and	fchownat() functions will fail if:

       EBADF	       For fchown() the	fildes argument	is not	an  open  file
		       descriptor and.

		       For  fchownat(),	 the path argument is not absolute and
		       the fildes argument is not AT_FDCWD or an open file de-
		       scriptor.

       EIO	       An  I/O error occurred while reading from or writing to
		       the file	system.

       EINTR	       A signal	was caught during execution of the function.

       ENOLINK	       The fildes argument points to a remote machine and  the
		       link to that machine is no longer active.

       EINVAL	       The group or owner argument is out of range.

       EROFS	       The named file referred to by fildes resides on a read-
		       only file system.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See below.		   |
       +-----------------------------+-----------------------------+

       The chown(), fchown(), and lchown() functions are Standard. The	fchow-
       nat() function is Evolving.

       The chown() and fchownat() functions are	Async-Signal-Safe.

SEE ALSO
       chgrp(1),  chown(1), chmod(2), fpathconf(2), system(4), attributes (5),
       standards(5)

SunOS 5.10			  20 Jan 2003			      chown(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=chown&sektion=2&manpath=SunOS+5.10>

home | help