fchown()

Change the user ID and group ID of a file

Synopsis:

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

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

Arguments:

fd

A file descriptor for the file whose ownership you want to change.

owner

The user ID of the new owner.

group

The group ID of the new owner.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The fchown() function changes the user ID and group ID of the file referenced by fd to be the numeric values contained in owner and group, respectively.

Only processes with an effective user ID equal to the user ID of the file, or with appropriate privileges (for example, the superuser) may change the ownership of a file.

The _POSIX_CHOWN_RESTRICTED flag is enforced. This means that only the superuser may change the ownership of a file. The group of a file may be changed by the superuser, or also by a process with the effective user ID equal to the user ID of the file, if (and only if) owner is equal to the user ID of the file and group is equal to the effective group ID of the calling process.

If the fd argument refers to a regular file, the set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode are cleared if the function is successful.

If fchown() succeeds, the st_ctime field of the file is marked for update.

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EBADF

Invalid file descriptor.

EPERM

The effective user ID doesn't match the owner of the file, or the calling process doesn't have appropriate privileges.

EROFS

The named file resides on a read-only filesystem.

Examples:

/*
 * Change the ownership of a list of files
 * to the current user/group
 */
#include <stdio.h>
#include <fcntl.h>
#include <sys/types.h>
#include <unistd.h>

int main( int argc, char **argv )
  {
    int i;
    int ecode = 0;
    int fd;

    for( i = 1; i < argc; i++ ) {
      if( ( fd = open( argv[i], O_RDONLY ) ) == -1 ) {
        perror( argv[i] );
        ecode++;
      }
      else if( fchown( fd, getuid(), getgid() ) == -1 ) {
        perror( argv[i] );
        ecode++;
      }

      close( fd );
    }
    return ecode;
  }

Classification:

POSIX 1003.1

See also:

chmod(), chown(), errno, fchmod(), fstat(), lchown(), open(), stat()