--- name: "lchown" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/chown/2" --- # lchown(2) change owner and group of a file Part of [chown(2)](/chown/2.md). ## NAME **chown**, **fchown**, **lchown**, **fchownat** – change owner and group of a file ## SYNOPSIS **#include \** *int*\ **chown**(*const char \*path*, *uid\_t owner*, *gid\_t group*); *int*\ **fchown**(*int fildes*, *uid\_t owner*, *gid\_t group*); *int*\ **lchown**(*const char \*path*, *uid\_t owner*, *gid\_t group*); *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 named by *path* or referenced by *fildes* 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 super-user. The **chown**() system call clears the set-user-id and set-group-id bits on the file. The **chown**() system call follows symbolic links to operate on the target of the link rather than the link itself. The **fchown**() system call is particularly useful when used in conjunction with the file locking primitives (see [flock(2)](/flock/2.md)). The **lchown**() system call is similar to **chown**() but does not follow symbolic links. The **fchownat**() system call is equivalent to the **chown**() and **lchown**() except in the case where *path* specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor *fd* instead of the current working directory. Values for *flag* are constructed by a bitwise-inclusive OR of flags from the following list, defined in ⟨fcntl.h⟩: - AT\_SYMLINK\_NOFOLLOW If *path* names a symbolic link, ownership of the symbolic link is changed. - AT\_SYMLINK\_NOFOLLOW\_ANY If *path* names a symbolic link, ownership of the symbolic link is changed. If any any other symbolic link is encountered it is not followed and an error is returned instead. - AT\_RESOLVE\_BENEATH If *path* does not reside in the hierarchy beneath the starting directory, an error is returned. - AT\_UNIQUE If *path* resolves to a vnode with multiple hard links, an error is returned. 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 id's may be left unchanged by specifying it as -1. ## RETURN VALUES The **chown()** function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. ## ERRORS The **chown**() and **lchown**() system calls will fail if: - \[EACCES\] Search permission is denied for a component of the path prefix. - \[EFAULT\] The *path* argument points outside the process's allocated address space. - \[ELOOP\] Too many symbolic links are encountered in translating the pathname. This is taken to be indicative of a looping symbolic link. - \[ELOOP\] If AT\_SYMLINK\_NOFOLLOW\_ANY is passed a symbolic link was encountered in translating the pathname. - \[ENAMETOOLONG\] A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. - \[ENOENT\] A component of *path* does not exist. - \[ENOTDIR\] A component of the path prefix is not a directory. The **fchown**() system call will fail if: - \[EBADF\] The *fildes* argument does not refer to a valid descriptor. - \[EINVAL\] The *fildes* argument refers to a socket, not a file. Any of these calls will fail if: - \[EINTR\] Its execution is interrupted by a signal. - \[EIO\] An I/O error occurs while reading from or writing to the file system. - \[EPERM\] The effective user ID does not match the owner of the file and the calling process does not have appropriate (i.e., root) privileges. - \[EROFS\] The named file resides on a read-only 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. - \[ENOTCAPABLE\] if AT\_RESOLVE\_BENEATH was passed and *path* does not reside in the directory hierarchy beneath the starting directory. - \[ENOTCAPABLE\] if AT\_UNIQUE was passed and *path* resolves to a vnode with multiple links. ## SEE ALSO [chgrp(1)](/chgrp/1.md), [chmod(2)](/chmod/2.md), [flock(2)](/flock/2.md), [chown(8)](/chown/8.md) ## STANDARDS The **chown**() system call is expected to conform to ISO/IEC 9945-1:1990 (“POSIX.1”). The **fchownat**() system call is expected to conform to POSIX.1-2008 . ## HISTORY The **chown**() function appeared in Version 7 AT&T UNIX. The **fchown**() system call appeared in 4.2BSD. The **chown**() and **fchown**() system calls were changed to follow symbolic links in 4.4BSD. The **lchown**() system call was added in FreeBSD 3.0 to compensate for the loss of functionality. The **fchownat**() system call appeared in OS X 10.10