chown()

Change the user ID and group ID of a file

Synopsis:

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

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

Arguments:

path: The name of the file whose ownership you want to change.
owner: The user ID of the new owner, or -1 if you don't want to change the owner.
group: The group ID of the new owner, or -1 if you don't want to change the group.

Library:

libc

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

Description:

The chown() function changes the user ID and group ID of the file specified by path to be the numeric values contained in owner and group, respectively.

If the named file is a symbolic link, chown() changes the ownership of the file or directory that the symbolic link refers to; lchown() changes the ownership of the symbolic link file itself.

Only processes with an effective user ID equal to the file's user ID or with the IOFUNC_ABILITYID_CHOWN ability (see iofunc_ability_check()) may change the ownership of a file.

If the _POSIX_CHOWN_RESTRICTED flag (tested via the _PC_CHOWN_RESTRICTED limit in pathconf()), is set for path, then:

Only a process with the IOFUNC_ABILITYID_CHOWN ability may change the ownership of a file.
Changing the group ID is permitted to a process with an effective user ID equal to the file's user ID, but without the IOFUNC_ABILITYID_CHOWN ability, if and only if owner is equal to the file's user ID or -1 and group is equal either to the calling process's effective group ID or to one of its supplementary group IDs.

If chown() is successful, and:

the calling process's effective user ID isn't root
the path argument refers to a regular file
the file is executable (i.e., at least one of S_IXUSR, S_IXGRP, and S_IXOTH is set)

then the set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode are cleared.

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

Returns:

0: Success.
-1: An error occurred (errno is set); no changes were made to the user ID and group ID of the file.

Errors:

EACCES: Search permission is denied on a component of the path prefix.
ELOOP: Too many levels of symbolic links or prefixes.
ENAMETOOLONG: The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
ENOENT: A component of the path prefix doesn't exist, or the path arguments points to an empty string.
ENOSYS: The chown() function isn't implemented for the filesystem specified in path.
ENOTDIR: A component of the path prefix isn't a directory.
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 <stdlib.h>
#include <sys/types.h>
#include <unistd.h>

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

    for( i = 1; i < argc; i++ ) {
      if( chown( argv[i], getuid(), getgid() ) == -1 ) {
        perror( argv[i] );
        ecode++;
      }
    }
    exit( ecode );
  }

Classification:

POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes