CHOWN(2)

CHOWN(2) | System Calls Manual | CHOWN(2)

# NAME

`chown`, `lchown`, `fchown`, `fchownat` —
change owner and group of a file

# LIBRARY

Standard C Library (libc, -lc)

# 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>`

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 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 super-user.

When called to change the owner of a file, `chown`(), `lchown`() and `fchown`() clear the set-user-id (`S_ISUID`) bit on the file. When a called to change the group of a file, `chown`(), `lchown`() and `fchown`() clear the set-group-id (`S_ISGID`) bit on the file. These actions are taken to prevent accidental or mischievous creation of set-user-id and set-group-id programs.

`lchown`() is like `chown`() except in the case where the named file is a symbolic link, in which case `lchown`() changes the owner and group of the link, while `chown`() changes the owner and group of the file the link references.

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

`fchownat`() works the same way as `chown`() (or `lchown`() if `AT_SYMLINK_NOFOLLOW` is set in flag) except if path is relative. In that case, it is looked up from a directory whose file descriptor was passed as fd. Search permission is required on this directory. fd can be set to `AT_FDCWD` in order to specify the current directory.

One of the owner or group id's may be left unchanged by specifying it as (uid_t)-1 or (gid_t)-1 respectively.

# RETURN VALUES

The `chown`(), `lchown`(), `fchown`(), and `fchownat`() functions return the value 0 if successful; 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 will be unchanged if:

[`EACCES`]
  Search permission is denied for a component of the path prefix.
[`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.
[`ELOOP`]
  Too many symbolic links were encountered in translating the pathname.
[`ENAMETOOLONG`]
  A component of a pathname exceeded {`NAME_MAX`} characters, or an entire path name exceeded {`PATH_MAX`} characters.
[`ENOENT`]
  The named file does not exist.
[`ENOTDIR`]
  A component of the path prefix is not a directory.
[`EPERM`]
  The effective user ID is not the super-user.
[`EROFS`]
  The named file resides on a read-only file system.

In addition, `fchownat`() will fail if:

[`EBADF`]
  path does not specify an absolute path and fd is neither `AT_FDCWD` nor a valid file descriptor open for reading or searching.
[`ENOTDIR`]
  path is not an absolute path and fd is a file descriptor associated with a non-directory file.

`fchown`() will fail if:

[`EBADF`]
  fd does not refer to a valid descriptor.
[`EINVAL`]
  fd refers to a socket, not a file.
[`EIO`]
  An I/O error occurred while reading from or writing to the file system.
[`EPERM`]
  The effective user ID is not the super-user.
[`EROFS`]
  The named file resides on a read-only file system.

# SEE ALSO

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

# STANDARDS

The `chown`() function deviates from the semantics defined in IEEE Std 1003.1-1990 (“POSIX.1”), which specifies that, unless the caller is the super-user, both the set-user-id and set-group-id bits on a file shall be cleared, regardless of the file attribute changed. The `lchown`() and `fchown`() functions, as defined by X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”), provide the same semantics. `fchownat`() conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

To retain conformance to these standards, compatibility interfaces are provided by the POSIX Compatibility Library (libposix, -lposix) as follows:

- The `chown`() function conforms to IEEE Std 1003.1-1990 (“POSIX.1”) and X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”).
- The `lchown`() and `fchown`() functions conform to X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”).

# HISTORY

The `chown`() function call appeared in Version 1 AT&T UNIX. The `fchown`() function call appeared in 4.2BSD.

The `chown`() and `fchown`() functions were changed to follow symbolic links in 4.4BSD. The `lchown`() function call appeared in NetBSD 1.3.

September 1, 2019 | NetBSD 9.0