Man Pages

chown(3p) - phpMan chown(3p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (consult 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 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  appro-
              priate 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 sub-
              stituted 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 regula-
       tions. Version 7 and 4.3 BSD permit only the superuser to change the user ID of a file. Some  government  agen-
       cies  (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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                            CHOWN(3P)