[Previous]
[Contents]
[Next]

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 );

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.

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

In QNX4.1 or later, the _POSIX_CHOWN_RESTRICTED flag is enforced. This means that only the super user may change the ownership of a file. The group of a file may be changed by the super user, 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 path 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 chown() succeeds, the st_ctime field of the file is marked for update.

Returns:

0
Success
-1
An error occurred. errno is set to indicate the error.

Errors:

EACCES
Search permission is denied on a component of the path prefix.
ENAMETOOLONG
The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
ENOTDIR
A component of the path prefix is not a directory.
ENOENT
A component of the path prefix does not exist, or the path arguments points to an empty string.
EPERM
The effective user ID does not match the owner of the file, or the calling process does not have appropriate privileges.
EROFS
The named file resides on a read-only file system.

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++;
      }
    }
    return( ecode );
  }

Classification:

POSIX 1003.1

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread Yes

See also:

chmod(), errno, fstat(), open(), stat()


[Previous]
[Contents]
[Next]