chown(2)




NAME

     chown, lchown, fchown, fchownat - change owner and group  of
     a file


SYNOPSIS

     #include <unistd.h>
     #include <sys/types.h>

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

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

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

     int fchownat(int fildes,  const  char  *path,  uid_t  owner,
     gid_t group, int flag);


DESCRIPTION

     The chown() function sets the owner ID and group ID  of  the
     file  specified  by  path  or  referenced  by  the open file
     descriptor fildes to owner and group respectively. If  owner
     or  group  is  specified  as -1, chown() does not change the
     corresponding ID of the file.

     The  lchown() function sets the owner ID and group ID of the
     named  file  in the same manner as chown(), unless 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.

     The fchownat() function sets the owner ID and  group  ID  of
     the named  file  in the same manner as chown(). If, however,
     the path argument is relative, the path is resolved relative
     to  the  fildes  argument  rather  than  the current working
     directory.  If the fildes argument  has  the  special  value
     FDCWD,  the  path  path  resolution  reverts back to current
     working directory relative.  If the flag argument is set  to
     SYMLNK,  the  function behaves like lchown() with respect to
     symbolic links. If the path argument is absolute, the fildes
     argument  is  ignored.   If  the  path  argument  is  a null
     pointer, the function behaves like fchown().

     If  chown(), lchown(), fchown(), or fchownat() is invoked by
     a  process  other  than super-user, the set-user-ID and set-
     group-ID bits of the file mode, S_ISUID and  S_ISGID respec-
     tively, are cleared (see  chmod(2)).

     The  operating  system  provides  a  configuration   option,
     {_POSIX_CHOWN_RESTRICTED}, to restrict ownership changes for
     the   chown(),  lchown(),  and   fchown()  functions.   When
     {_POSIX_CHOWN_RESTRICTED}  is  not  in  effect,  either  the
     effective user ID of the process must match the owner of the
     file  or  the  process  must be the super-user to change the
     ownership of a file. When  {_POSIX_CHOWN_RESTRICTED}  is  in
     effect  (the  default  behavior), the chown(), lchown(), and
     fchown() functions, for users other than super-user, prevent
     the  owner  of  the  file from changing the owner ID  of the
     file and restrict the change of the group of the file to the
     list  of  supplementary group IDs. To set this configuration
     option, include the following line in /etc/system:

          set rstchown = 1

     To disable  this  option,  include  the  following  line  in
     /etc/system:

          set rstchown = 0

     See system(4) and  fpathconf(2).

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


RETURN VALUES

     Upon successful completion, 0 is returned. Otherwise, -1  is
     returned,  the  owner  and  group  of  the named file remain
     unchanged, and errno is set to indicate the error.


ERRORS

     The chown(), lchown(), and fchownat()functions will fail if:

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

     EFAULT
           The path argument points to an illegal address and for
           fchownat(),   the   file   descriptor  has  the  value
           AT_FDCWD.

     EINTR A signal  was  caught  during  the  execution  of  the
           chown() or lchown() function.

     EINVAL
           The group or owner argument is out of range.

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

     ELOOP Too many symbolic links were encountered in  translat-
           ing path.

     ENAMETOOLONG
           The length of the path argument exceeds {PATH_MAX}, or
           the  length  of  a  path  component exceeds {NAME_MAX}
           while {_POSIX_NO_TRUNC} is in effect.

     ENOLINK
           The path argument points to a remote machine  and  the
           link to that machine is no longer active.

     ENOENT
           Either a component of the  path  prefix  or  the  file
           referred  to by path does not exist or is a null path-
           name.

     ENOTDIR
           A component of the path prefix of path is not a direc-
           tory,  or  the path supplied to fchownat() is relative
           and the file descriptor provided does not refer  to  a
           valid directory.

     EPERM The effective user ID does not match the owner of  the
           file   or  the  process  is  not  the  super-user  and
           _POSIX_CHOWN_RESTRICTED indicates that such  privilege
           is required.

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

     The fchown() and fchownat() functions will fail if:

     EBADF For fchown() the fildes argument is not an  open  file
           descriptor and.

     EBADF For fchownat(), the path argument is not absolute  and
           the  fildes  argument  is not AT_FDCWD or an open file
           descriptor.

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

     EINTR A signal was caught during execution of the function.

     ENOLINK
           The fildes argument points to a remote machine and the
           link to that machine is no longer active.

     EINVAL
           The group or owner argument is out of range.

     EPERM The effective user ID does not match the owner of  the
           file,  or  the  process  is  not  the  super-user  and
           _POSIX_CHOWN_RESTRICTED indicates that such  privilege
           is required.

     EROFS The named file referred to  by  fildes  resides  on  a
           read-only file system.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
  |         ATTRIBUTE TYPE      |         ATTRIBUTE VALUE     |
  |  ___________________________|_____________________________|__
  |   Interface Stability       |   chown()    is     Standard|
  |                             |   fchownat() is Evolving    |
  | ____________________________|_____________________________|_
  |  MT-Level                   |  chown() and  fchownat() are|
  |                             |  Async-Signal-Safe          |
  |_____________________________|_____________________________|


SEE ALSO

     chgrp(1),  chown(1),  chmod(2),   fpathconf(2),   system(4),
     attributes (5)


Man(1) output converted with man2html