CHOWN(3P)                                           POSIX Programmer's Manual                                          CHOWN(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

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 with-
          out 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  imple-
       mentation-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 priv-
              ileges 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 val-
       ues, 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 supe-
       ruser 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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                     CHOWN(3P)