chown() — Change the owner or group of a file or directory

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <unistd.h>

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

General description

Changes the owner or group (or both) of a file. pathname is the name of the file whose owner or group you want to change. owner is the user ID (UID) of the new owner of the file. group is the group ID (GID) of the new group for the file.

If _POSIX_CHOWN_RESTRICTED is defined in the unistd.h header file, a process can change the group of a file only if one of these is true:

The process has appropriate privileges.
Or all of the following are true:
1. The effective user ID of the process is equal to the user ID of the file owner.
2. The owner argument is equal to the user ID of the file owner or (uid_t)-1,
3. The group argument is either the effective group ID or a supplementary group ID of the calling process.

If pathname is a regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set, chown() clears the set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode and returns successfully.

If pathname is not a regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set, chown() clears the set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits of the file.

When chown() completes successfully, it marks the st_ctime field of the file to be updated.

Special behavior for XPG4.2: If owner or group is specified as (uid_t)-1 or (gid_t)-1 respectively, the corresponding ID of the file is unchanged.

Returned value

If successful, chown() updates the owner, group, and change time for the file and returns 0.

If unsuccessful, chown() returns -1 and sets errno to one of the following values:

Error Code: Description
EACCES: The process does not have search permission on some component of the pathname prefix.
EINTR: Added for XPG4.2: The chown() function was interrupted by a signal which was caught.
EINVAL: owner or group is not a valid user ID (UID) or group ID (GID).
EIO: Added for XPG4.2: An I/O error occurred while reading or writing to the file system.
ELOOP: A loop exists in symbolic links. This error is issued if the number of symbolic links detected in the resolution of pathname is greater than POSIX_SYMLOOP (a value defined in the limits.h header file).
ENAMETOOLONG: pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using pathconf().
ENOENT: There is no file named pathname, or the pathname argument is an empty string.
ENOTDIR: Some component of the pathname prefix is not a directory.
EPERM: The effective user ID of the calling process does not match the owner of the file, or the calling process does not have appropriate privileges, that is, superuser authority (UID=0).
EROFS: pathname is on a read-only file system.

Example

CELEBC12

⁄* CELEBC12

   This example changes the owner and group of a file.

 *⁄
#define _POSIX_SOURCE
#include <unistd.h>
#include <sys⁄stat.h>
#include <sys⁄types.h>
#undef _POSIX_SOURCE
#include <stdio.h>

main() {
  char fn[]=".⁄temp.file";
  FILE *stream;
  struct stat info;

  if ((stream = fopen(fn, "w")) == NULL)
    perror("fopen() error");
  else {
    fclose(stream);
    stat(fn, &info);
    printf("original owner was %d and group was %d\n", info.st_uid,
           info.st_gid);
    if (chown(fn, 25, 0) != 0)
      perror("chown() error");
    else {
      stat(fn, &info);
      printf("after chown(), owner is %d and group is %d\n",
             info.st_uid, info.st_gid);
    }
    unlink(fn);
  }
}

Output

original owner was 0 and group was 0
after chown(), owner is 25 and group is 0