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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       chown, fchownat -- change owner and group of a file relative to
       directory file descriptor

SSYYNNOOPPSSIISS
       #include <unistd.h>

       int chown(const char *_p_a_t_h, uid_t _o_w_n_e_r, gid_t _g_r_o_u_p);
       int fchownat(int _f_d, const char *_p_a_t_h, uid_t _o_w_n_e_r, gid_t _g_r_o_u_p,
           int _f_l_a_g);

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

       The _p_a_t_h 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 _o_w_n_e_r and _g_r_o_u_p, 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 _p_a_t_h:

        *  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 _o_w_n_e_r is equal to the file's user ID or
           (uuiidd__tt)-1 and _g_r_o_u_p 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 _c_h_o_w_n().  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 _c_h_o_w_n() 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 _o_w_n_e_r or _g_r_o_u_p is specified as (uuiidd__tt)-1 or (ggiidd__tt)-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, _c_h_o_w_n() shall mark for update the last file
       status change timestamp of the file.

       The _f_c_h_o_w_n_a_t() function shall be equivalent to the _c_h_o_w_n() and _l_c_h_o_w_n()
       functions except in the case where _p_a_t_h specifies a relative path. In
       this case the file to be changed is determined relative to the
       directory associated with the file descriptor _f_d instead of the current
       working directory. If the file descriptor was opened without O_SEARCH,
       the function shall check whether directory searches are permitted using
       the current permissions of the directory underlying the file
       descriptor. If the file descriptor was opened with O_SEARCH, the
       function shall not perform the check.

       Values for _f_l_a_g are constructed by a bitwise-inclusive OR of flags from
       the following list, defined in _<_f_c_n_t_l_._h_>:

       AT_SYMLINK_NOFOLLOW
             If _p_a_t_h names a symbolic link, ownership of the symbolic link is
             changed.

       If _f_c_h_o_w_n_a_t() is passed the special value AT_FDCWD in the _f_d parameter,
       the current working directory shall be used and the behavior shall be
       identical to a call to _c_h_o_w_n() or _l_c_h_o_w_n() respectively, depending on
       whether or not the AT_SYMLINK_NOFOLLOW bit is set in the _f_l_a_g argument.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, these functions shall return 0.  Otherwise,
       these functions shall return -1 and set _e_r_r_n_o to indicate the error. If
       -1 is returned, no changes are made in the user ID and group ID of the
       file.

EERRRROORRSS
       These functions shall fail if:

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

       EELLOOOOPP  A loop exists in symbolic links encountered during resolution of
              the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a component of a pathname is longer than
              {NAME_MAX}.

       EENNOOEENNTT A component of _p_a_t_h does not name an existing file or _p_a_t_h is an
              empty string.

       EENNOOTTDDIIRR
              A component of the path prefix names an existing file that is
              neither a directory nor a symbolic link to a directory, or the
              _p_a_t_h argument contains at least one non-<slash> character and
              ends with one or more trailing <slash> characters and the last
              pathname component names an existing file that is neither a
              directory nor a symbolic link to a directory.

       EEPPEERRMM  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.

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

       The _f_c_h_o_w_n_a_t() function shall fail if:

       EEAACCCCEESS _f_d was not opened with O_SEARCH and the permissions of the
              directory underlying _f_d do not permit directory searches.

       EEBBAADDFF  The _p_a_t_h argument does not specify an absolute path and the _f_d
              argument is neither AT_FDCWD nor a valid file descriptor open
              for reading or searching.

       EENNOOTTDDIIRR
              The _p_a_t_h argument is not an absolute path and _f_d is a file
              descriptor associated with a non-directory file.

       These functions may fail if:

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

       EEIINNTTRR  The _c_h_o_w_n() function was interrupted by a signal which was
              caught.

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

       EELLOOOOPP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a pathname exceeds {PATH_MAX}, or pathname
              resolution of a symbolic link produced an intermediate result
              with a length that exceeds {PATH_MAX}.

       The _f_c_h_o_w_n_a_t() function may fail if:

       EEIINNVVAALL The value of the _f_l_a_g argument is not valid.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Although _c_h_o_w_n() 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.

RRAATTIIOONNAALLEE
       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 POSIX.1-2008 uses _m_a_y 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 _c_h_o_w_n() 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.

       The purpose of the _f_c_h_o_w_n_a_t() function is to enable changing ownership
       of files in directories other than the current working directory
       without exposure to race conditions. Any part of the path of a file
       could be changed in parallel to a call to _c_h_o_w_n() or _l_c_h_o_w_n(),
       resulting in unspecified behavior. By opening a file descriptor for the
       target directory and using the _f_c_h_o_w_n_a_t() function it can be guaranteed
       that the changed file is located relative to the desired directory.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_h_m_o_d(), _f_p_a_t_h_c_o_n_f(), _l_c_h_o_w_n()

       The Base Definitions volume of POSIX.1-2008, <<ffccnnttll..hh>>, <<ssyyss__ttyyppeess..hh>>,
       <<uunniissttdd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                             CHOWN(3)
