chown()

Updated: April 19, 2023

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:

If chown() is successful, and:

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 argument points to an empty string.
ENOSYS
The chown() function isn't implemented for the filesystem underlying the path 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