wcs_chown(2)                                               wcs_chown(2)

  chown()

  NAME

    chown(), wcs_chown(), fchown(), lchown(), wcs_lchown() - change owner and
    group of a file

  SYNOPSIS

    #include 

    int chown (const char *path, uid_t owner, gid_t group)
    int wcs_chown (const wchar_t *path, uid_t owner, gid_t group)
    int fchown (int fildes, uid_t owner, gid_t group)
    int lchown (const char *path, uid_t owner, gid_t group)
    int wcs_lchown (const wchar_t *path, uid_t owner, gid_t group)

  DESCRIPTION

    These calls change the owner identifier (ID) and group ID of a file. A
    process must have the appropriate permissions on a file to change
    ownership. The chown(2) and wcs_chown(2) functions are identical, as are
    the lchown(2) and wcs_lchown(2) functions, except that the wcs_chown(2)
    and wcs_lchown(2) functions accept wide characters in the path argument.

    The owner ID and group ID of the file named by path or referenced by
    fildes is changed as specified by the arguments owner and group. The owner
    of a file may change the group to a group of which he or she is a member.

    The chown(2) and lchown(2) utilities behave nearly identically, except if
    the file specified by path is a symbolic link: in that case, chown(2) will
    change the ownership on the file referenced by the symbolic link, and
    lchown(2) will change the ownership on the symbolic link file itself.

    All of these calls clear the set-user-id and set-group-id bits on the file
    to prevent accidental or malicious creation of set-user-id and set-group-
    id programs.

    One of the owner or group IDs may be left unchanged by specifying it as -
    1.

    Note that with Windows, it is not usually possible to give away ownership
    of a file. It is possible, however, to take ownership of a file, if the
    effective user ID of the process has the Windows Take Ownership permission
    for the file. Any user with the Windows privileges SE_BACKUP and
    SE_RESTORE may give away ownership of a file. (Normally this is only users
    with Administrator or Backup Operator privileges.)

  RETURN VALUES

    These functions return zero if the operation was successful; they return -
    1 if an error occurs, placing a more specific error code in the global
    variable errno.

  ERRORS

    The chown(2), wcs_chown(2), lchown(2), and wcs_lchown(2) functions will
    fail and the file will be unchanged if:

    [EACCES]
        Search permission is denied for a component of the path prefix.

    [EINVAL]
        The pathname contains a character with the high-order bit set, or the
        operation is not valid on this type of file, or the owner or group ID
        is not valid.

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

    [ELOOP]
        Too many symbolic links were encountered in translating the pathname.

    [ENAMETOOLONG]

        A component of a pathname exceeded {NAME_MAX} characters, or an entire
        pathname exceeded {PATH_MAX} characters.

    [ENOENT]
        The named file does not exist.

    [ENOTDIR]
        A component of the path prefix is not a directory.

    [EPERM]
        The effective user ID does not have the permissions required.

    [EROFS]
        The named file resides on a read-only file system.

    [EFAULT]
        Path points outside the process's allocated address space.

    The fchown(2) function will fail and the file will be unchanged if:

    [EBADF]
        The fildes doesn't describe an open file.

    [EINTR]
        The call was interrupted by a signal.

    [EINVAL]
        The owner or group ID is not valid, or the operation is not valid on
        this type of file.

    [EIO]
        An I/O error occurred.

    [EPERM]
        The effective user ID does not have the permissions required.

    [EROFS]
        The file indicated by fildes resides on a read-only file system.

    The lchown(2) call can also fail for these reasons:

    [EINTR]
        The execution of the function was interrupted by a signal.

    [EIO]
        An I/O error occurred.

    [EOPNOTSUPP]
        The path names a symbolic link and the implementation does not support
        setting the owner or group of a symbolic link. (This error should not
        occur on an system.)

    [EROFS]
        The file indicated by fildes resides on a read-only file system.

  SEE ALSO

    chgrp(1)

    chmod(2)

  USAGE NOTES

    All of these functions are thread safe.

    The following functions are async-signal safe: chown, fchown, wcs_chown.
    The following functions are not async-signal safe: lchown, wcs_lchown.