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

FreeBSD Manual Pages


home | help
CHOWN(2)		  FreeBSD System Calls Manual		      CHOWN(2)

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

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

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

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

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

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

     The owner ID and group ID of the file (or link) named by path or refer-
     enced by fd is changed as specified by the	arguments owner	and group.
     The owner of a file may change the	group to a group of which he or	she is
     a member, but the change owner capability is restricted to	the superuser.

     By	default, chown() clears	the set-user-ID	and set-group-ID bits on the
     file to prevent accidental	or mischievous creation	of set-user-ID and
     set-group-ID programs.  This behaviour can	be overridden by setting the
     sysctl(8) variable	fs.posix.setuid	to zero.

     lchown() operates similarly to how	chown()	operated on older systems, and
     does not follow symbolic links.  It allows	the owner and group of a sym-
     bolic link	to be set.

     The fchownat() function is	equivalent to either the chown() or lchown()
     function depending	on the value of	flag (see below), except that where
     path specifies a relative path, the file whose ownership is changed is
     determined	relative to the	directory associated with file descriptor fd
     instead of	the current working directory.

     If	fchownat() is passed the special value AT_FDCWD	(defined in <fcntl.h>)
     in	the fd parameter, the current working directory	is used	and the	behav-
     ior is identical to a call	to chown() or lchown(),	depending on whether
     or	not the	AT_SYMLINK_NOFOLLOW bit	is set in flag.

     Values for	flag are constructed by	bitwise-inclusive ORing	flags from the
     following list defined in <fcntl.h>:

	   AT_SYMLINK_NOFOLLOW	If path	names a	symbolic link, then the	owner-
				ship of	the symbolic link is changed.

     fchown() is particularly useful when used in conjunction with the file
     locking primitives	(see flock(2)).

     One of the	owner or group IDs may be left unchanged by specifying it as

     Zero is returned if the operation was successful; -1 is returned if an
     error occurs, with	a more specific	error code being placed	in the global
     variable errno.

     chown(), lchown(),	and fchownat() will fail and the file or link will be
     unchanged if:

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

     [ENAMETOOLONG]	A component of a pathname exceeded {NAME_MAX} charac-
			ters, or an entire path	name exceeded {PATH_MAX} char-

     [ENOENT]		The named file does not	exist.

     [EACCES]		Search permission is denied for	a component of the
			path prefix.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [EPERM]		The effective user ID is not the superuser.

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

     [EFAULT]		path points outside the	process's allocated address

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

     Additionally, fchownat() will fail	if:

     [EBADF]		The path argument does not specify an absolute path
			and the	fd argument is neither AT_FDCWD	nor a valid
			file descriptor	open for reading.

     fchown() will fail	if:

     [EBADF]		fd does	not refer to a valid descriptor.

     [EINVAL]		fd refers to a socket, not a file.

     [EPERM]		The effective user ID is not the superuser.

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

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

     chgrp(1), chmod(2), flock(2), chown(8)

     The chown(), fchown(), fchownat(),	and lchown() functions are expected to
     conform to	IEEE Std 1003.1-2008 (``POSIX.1'').

     A chown() system call first appeared in Version 1 AT&T UNIX.  Since
     Version 6 AT&T UNIX it supports changing the group	as well, and in
     Version 7 AT&T UNIX group was made	a separate argument.

     The fchown() system call first appeared in	4.2BSD.

     The chown() and fchown() functions	were changed to	follow symbolic	links
     in	4.4BSD;	therefore, and for compatibility with AT&T System V Release 4
     UNIX, the lchown()	function was added to OpenBSD 2.1.

     The fchownat() function appeared in OpenBSD 5.0.

FreeBSD	11.1		      September	21, 2017		  FreeBSD 11.1


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

home | help