lchown()

Change the user ID and group ID of a file or symbolic link

Synopsis:

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

int lchown( 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 lchown() 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. It's similar to chown(), except in the case where the named file is a symbolic link. In this case, lchown() changes the ownership of the symbolic link file itself, while chown() changes the ownership of the file or directory to which the symbolic link refers.

Returns:

0: Success.
-1: An error occurred (errno is set).

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 lchown() 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( lchown( argv[i], getuid(), getgid() ) == -1 ) {
        perror( argv[i] );
        ecode++;
      }
    }
    return( ecode );
  }

Classification:

POSIX 1003.1

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