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