fchown -- Change File Owner or Group (Using File Descriptor)

SYNOPSIS

 #include <sys/types.h>
 #include <unistd.h>

 int fchown(int fileDescriptor, uid_t owner, gid_t group);

DESCRIPTION

fchown changes the owner or owning group of a file. It can be used with either regular files or special files, such as directories or FIFO files. fileDescriptor is the file descriptor for the file. owner is the user ID. group is the group ID.

OpenEdition implements a restricted fchown for all files. A call to fchown can succeed in only one of two ways:

the caller is a superuser
the effective user ID is the same as the owner of the file, which is equal to the owner argument to fchown, and the group argument is the effective group ID or one of the user's supplementary ID's.

Because _POSIX_CHOWN_RESTRICTED is defined for OpenEdition in <unistd.h> with a value of 1, a process can change the group only if the process has the appropriate privileges or its effective user ID is the same as the user ID of the file owner and group is the effective group ID or one of its supplementary group IDs.

If fileDescriptor refers to a regular file and an S_IXUSR, S_IXGRP, or S_IXOTH bit is set in file permissions, fchown clears the S_ISUID and S_ISGID bits of the permissions and returns successfully. If fileDescriptor refers to a special file and an S_IXUSR, S_IXGRP, or S_IXOTH bit is set, fchown clears the S_ISUID and S_ISGID bits of the file.

PORTABILITY

The fchown function is defined by the POSIX.1a draft standard.

RETURN VALUE

fchown returns 0 if successful and a -1 if not successful.

EXAMPLE

The following example illustrates the use of fchown to change a file's owning group ID.

Note: You must specify the posix option when compiling this example.

  #include <sys/types.h>
  #include <unistd.h>
  #include <fcntl.h>
  #include <string.h>
  #include <stdio.h>
  #include <sys/stat.h>
  #include <grp.h>


  main()
  {
     int fd;
     gid_t grpid;
     struct stat fileStatus;
     struct group *gr_data;
     char words[] = "Test File";

        /* Create a test file.                                */
     if ((fd = creat("test.file", S_IRUSR|S_IWUSR)) == -1) {
        perror("creat error");
        _exit(1);
     }
     else
        write(fd, words, strlen(words));

        /* Get group 10 for new group.                        */
     gr_data = getgrnam("QA");
     if (gr_data == NULL) {
        perror("getgrnam error");
        _exit(1);
     }
     grpid = gr_data->gr_gid;

        /* Get file status and then print user and group IDs. */
     if (fstat(fd ,&fileStatus) != 0)  {
        perror("fstat error");
        _exit(1);
     }
     else  {
        printf("UID=%d GID=%d n", (int) fileStatus.st_uid,
                (int) fileStatus.st_gid);
          /* Change file ownership.                           */
        if (fchown(fd, seteuid(), grpid) != 0)
           perror("fchown error");
        printf("UID=%d GID=%d n", (int) fileStatus.st_uid,
                (int) fileStatus.st_gid);
     }
  close(fd);
  }