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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
     #include <unistd.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	fd, uid_t owner, gid_t group);

     #include <fcntl.h>
     #include <unistd.h>

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

DESCRIPTION
     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.

     The flag argument is the bitwise OR of zero or more of the	following val-
     ues:

	   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
     -1.

RETURN VALUES
     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the
     error.

ERRORS
     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 pathname (including the terminating
			NUL) exceeded PATH_MAX bytes.

     [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
			space.

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

     Additionally, fchownat() will fail	if:

     [EINVAL]		The value of the flag argument was neither zero	nor
			AT_SYMLINK_NOFOLLOW.

     [EBADF]		The path argument specifies a relative path and	the fd
			argument is neither AT_FDCWD nor a valid file descrip-
			tor.

     [ENOTDIR]		The path argument specifies a relative path and	the fd
			argument is a valid file descriptor but	it does	not
			reference a directory.

     [EACCES]		The path argument specifies a relative path but	search
			permission is denied for the directory which the fd
			file descriptor	references.

     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.

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

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

HISTORY
     The 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.1cBSD.

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

     The fchownat() system call	has been available since OpenBSD 5.0.

FreeBSD	13.0		      September	10, 2015		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

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

home | help