chown(), fchown(), lchown()

change file ownership 

Function

SYNOPSIS

#include <sys/types.h>

#include <unistd.h>

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

int fchown(int fildes, uid_t owner, gid_t group);

int lchown(const char *pathname, uid_t owner, gid_t group);

DESCRIPTION

The chown() function sets the owner ID and group ID of the file that pathname specifies. For this call to succeed, the effective user ID of the process must match the owner of the file, or the process must have appropriate privileges.

The fchown() function has the same effect as chown() except that the file whose ownership is to be changed is specified by file descriptor rather than path name.

The lchown() function has the same effect as 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.

When successfully completed, these functions mark the st_ctime field of the file for update.

If the owner or group is specified as (uid_t)-1 or (gid_t)-1 respectively, the corresponding ID of the file is unchanged.

PARAMETERS

pathname 

Points to the path name of the file to modify.

fildes 

Is the file descriptor of an open file.

owner 

Is the new user ID for the file.

group 

Is the new group ID for the file.

RETURN VALUES

If successful, chown(), fchown(), and lchown() return zero. On failure, they return -1, make no changes to the owner or group of the file, and set errno one of the following:

EACCES 

Search permission is denied on a component of the path name prefix of pathname.

EBADF 

fildes is not a valid file descriptor.

EFAULT 

pathname points outside the allocated address space of the process.

EINTR 

A signal interrupted the call.

EINVAL 

group or owner is invalid.

EIO 

An I/O error occurred while reading from or writing to the file system.

ENAMETOOLONG 

The length of pathname exceeds PATH_MAX or a path name component is longer than NAME_MAX while _POSIX_NO_TRUNC is in effect.

ENOENT 

Either a component of the pathname prefix or the file that pathname refers to does not exist or is a null path name.

ENOTDIR 

A component of the path name prefix of pathname refers is not a directory.

EPERM 

The effective user ID does not match the owner of the file or the calling process does not have appropriate privileges.

CONFORMANCE

chown(), fchown(): POSIX.1 (1996) with exceptions.

lchown(): UNIX 98 with exceptions.

MULTITHREAD SAFETY LEVEL

chown(): Async-signal-safe.

fchown(), lchown(): MT-Safe.

PORTING ISSUES

There are differences in how the NuTCRACKER Platform handles file ownership, compared to the referenced standard. Refer to the struct stat page, to File Management in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide, and also Security in the API-Specific Porting Issues chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide.

Windows does not currently support symbolic links, so lchown() is equivalent to chown().

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
chmod(), fchmod(), symlink()

Miscellaneous:
struct stat

PTC MKS Toolkit 10.5 Documentation Build 40.