NAME

       chown - change owner and group of a file

SYNOPSIS

       #include <unistd.h>

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

DESCRIPTION

       The chown() function shall change the user and group ownership of a file.

       The path argument points to a pathname naming a file. The user ID and group ID of the named file shall be
       set to 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
       may change the ownership of a file. If _POSIX_CHOWN_RESTRICTED is in effect for path:

        * Changing the user ID is restricted to processes with appropriate privileges.

        * Changing  the group ID is permitted to a process with an effective user ID equal to the user ID of the
          file, but without appropriate privileges, if and only if owner is equal to the file's  user  ID  or  (
          uid_t)-1  and  group  is  equal  either  to  the  calling process' effective group ID or to one of its
          supplementary group IDs.

       If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file
       mode  are  set,  and the process does not have appropriate privileges, the set-user-ID (S_ISUID) and set-
       group-ID (S_ISGID) bits of the file mode shall be cleared upon successful return  from  chown().  If  the
       specified  file  is a regular file, one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode
       are set, and the process has appropriate privileges, it is implementation-defined whether the set-user-ID
       and  set-group-ID bits are altered. If the chown() function is successfully invoked on a file that is not
       a regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file  mode  are  set,  the
       set-user-ID and set-group-ID bits may be cleared.

       If  owner  or  group  is specified as ( uid_t)-1 or ( gid_t)-1, respectively, the corresponding ID of the
       file shall not be changed. If both owner and group are -1, the times need not be updated.

       Upon successful completion, chown() shall mark for update the st_ctime field of the file.

RETURN VALUE

       Upon successful completion, 0 shall be returned; otherwise,  -1  shall  be  returned  and  errno  set  to
       indicate the error. If -1 is returned, no changes are made in the user ID and group ID of the file.

ERRORS

       The chown() function shall fail if:

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

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       ENAMETOOLONG
              The  length  of  the  path  argument  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 path does not name an existing file or path is 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 and _POSIX_CHOWN_RESTRICTED indicates that such privilege is required.

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

       The chown() function may fail if:

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

       EINTR  The chown() function was interrupted by a signal which was caught.

       EINVAL The owner or group ID supplied is not a value supported by the implementation.

       ELOOP  More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.

       ENAMETOOLONG
              As  a result of encountering a symbolic link in resolution of the path argument, the length of the
              substituted pathname string exceeded {PATH_MAX}.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       Although chown() can be used on some implementations by the file owner to change the owner and  group  to
       any  desired  values,  the  only  portable  use  of this function is to change the group of a file to the
       effective GID of the calling process or to a member of its group set.

RATIONALE

       System III and System V allow a user to give away files; that is, the owner of a file may change its user
       ID  to  anything.  This  is  a  serious  problem for implementations that are intended to meet government
       security regulations. Version 7 and 4.3 BSD permit only the superuser to change the user ID  of  a  file.
       Some  government  agencies  (usually  not ones concerned directly with security) find this limitation too
       confining. This volume of IEEE Std 1003.1-2001 uses  may  to  permit  secure  implementations  while  not
       disallowing System V.

       System  III  and System V allow the owner of a file to change the group ID to anything. Version 7 permits
       only the superuser to change the group ID of a file. 4.3 BSD permits the owner to change the group ID  of
       a  file  to its effective group ID or to any of the groups in the list of supplementary group IDs, but to
       no others.

       The POSIX.1-1990 standard requires that the chown() function  invoked  by  a  non-appropriate  privileged
       process  clear  the  S_ISGID  and  the S_ISUID bits for regular files, and permits them to be cleared for
       other types of files. This is so that changes in accessibility do not accidentally cause files to  become
       security  holes.   Unfortunately,  requiring  these  bits to be cleared on non-executable data files also
       clears  the  mandatory  file  locking  bit  (shared  with  S_ISGID),  which  is  an  extension  on   many
       implementations  (it  first  appeared  in  System V). These bits should only be required to be cleared on
       regular files that have one or more of their execute bits set.

FUTURE DIRECTIONS

       None.

SEE ALSO

       chmod() , pathconf() , the Base Definitions volume of IEEE Std 1003.1-2001, <sys/types.h>, <unistd.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .