|If path names a symbolic link, ownership of the symbolic link is changed.|
If fchownat is passed the special value AT_FDCWD in the fd parameter, the current working directory is used and the behavior is identical to a call to chown or lchown respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in the flag argument.
One of the owner or group ids may be left unchanged by specifying it as -1.
The chown and lchown will fail and the file will be unchanged if:
[ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. [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 translating the pathname. [EPERM] The operation would change the ownership, but the effective user ID is not the super-user. [EPERM] The named file has its immutable or append-only flag set, see the chflags(2) manual page for more information. [EROFS] The named file resides on a read-only file system. [EFAULT] The path argument points outside the processs allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system.
The fchown system call will fail if:
[EBADF] The fd argument does not refer to a valid descriptor. [EINVAL] The fd argument refers to a socket, not a file. [EPERM] The effective user ID is not the super-user. [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.
In addition to the errors specified for chown and lchown, the fchownat system call may 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 searching. [EINVAL] The value of the flag argument is not valid. [ENOTDIR] The path argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory.
The chown system call is expected to conform to -p1003.1-90. The fchownat system call follows The Open Group Extended API Set 2 specification.
The chown function appeared in AT&T v7 . The fchown system call appeared in BSD 4.2 .
The chown system call was changed to follow symbolic links in BSD 4.4 . The lchown system call was added in
.Fx 3.0 to compensate for the loss of functionality.
The fchownat system call appeared in
.Fx 8.0 .