Manual Pages for UNIX Operating System command usage for man fchownat

System Calls                                             chown(2)



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

SYNOPSIS
     #include 
     #include 

     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
     AT_FDCWD,  the path resolution reverts back to current work-
     ing 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  that does not have {PRIV_FILE_SETID} asserted in



SunOS 5.11          Last change: 15 Sep 2010                    1






System Calls                                             chown(2)



     its effective set, the set-user-ID and set-group-ID bits  of
     the  file  mode,  S_ISUID  and   S_ISGID  respectively,  are
     cleared (see  chmod(2)). Additional restrictions apply  when
     changing the ownership to uid 0.


     The operating system defines several privileges to  override
     restrictions  on  the  chown() family of functions. When the
     {PRIV_FILE_CHOWN} privilege is asserted in the effective set
     of  the current process, there are no restrictions except in
     the special circumstances of changing ownership to  or  from
     uid   0.   When   the  {PRIV_FILE_CHOWN_SELF}  privilege  is
     asserted, ownership changes are restricted to the  files  of
     which  the  ownership  matches  the effective user ID of the
     current process.  If neither privilege is  asserted  in  the
     effective  set of the calling process, ownership changes are
     limited to changes of the group of the file to the  list  of
     supplementary group IDs and the effective group ID.


     The  file  system  provides  mount  options   rstchown   and
     norstchown  to  control  the default chown() behavior of the
     file system and NFS server. If rstchown is  not  in  effect,
     the  privilege  {PRIV_FILE_CHOWN_SELF} is implicitly granted
     to the user when attempting to give away files,  except  for
     files owned by uid 0.


     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
     All of these functions will fail if:

     EPERM    The effective user ID does not match the  owner  of
              the file and the {PRIV_FILE_CHOWN} privilege is not
              asserted in the effective set of the  calling  pro-
              cess,  or  the  {PRIV_FILE_CHOWN_SELF} privilege is
              not asserted in the effective set  of  the  calling
              process.



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





SunOS 5.11          Last change: 15 Sep 2010                    2






System Calls                                             chown(2)



     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
                     translating path.


     ENAMETOOLONG    The length  of  the  path  argument  exceeds
                     {PATH_MAX},  or  the  length  of a path com-
                     ponent     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 pathname.


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


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






SunOS 5.11          Last change: 15 Sep 2010                    3






System Calls                                             chown(2)



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

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

                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 writ-
                ing to the file system.


     EINTR      A signal was caught during execution of the func-
                tion.


     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.


     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         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | See below.                  |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|



     The chown() and fchownat() functions are Async-Signal-Safe.


     For chown(), fchown(), and lchown(), see standards(5).




SunOS 5.11          Last change: 15 Sep 2010                    4






System Calls                                             chown(2)



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




















































SunOS 5.11          Last change: 15 Sep 2010                    5