lchown(2) - NetBSD Manual Pages

CHOWN(2)                  NetBSD System Calls Manual                  CHOWN(2)


NAME

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


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <unistd.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 fd, uid_t owner, gid_t group);

     #include <fcntl.h>

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


DESCRIPTION

     The owner ID and group ID of the file named by path or referenced by fd
     is changed as specified by the arguments owner and group.  The owner of a
     file may change the group to a group of which he or she is a member, but
     the change owner capability is restricted to the super-user.

     When called to change the owner of a file, chown(), lchown() and fchown()
     clear the set-user-id (S_ISUID) bit on the file.  When a called to change
     the group of a file, chown(), lchown() and fchown() clear the set-group-
     id (S_ISGID) bit on the file.  These actions are taken to prevent acci-
     dental or mischievous creation of set-user-id and set-group-id programs.

     lchown() is like chown() except in the case where the named file is a
     symbolic link, in which case lchown() changes the owner and group of the
     link, while chown() changes the owner and group of the file the link ref-
     erences.

     fchown() is particularly useful when used in conjunction with the file
     locking primitives (see flock(2)).

     fchownat() works the same way as chown() (or lchown() if
     AT_SYMLINK_NOFOLLOW is set in flag) except if path is relative.  In that
     case, it is looked up from a directory whose file descriptor was passed
     as fd.  Search permission is required on this directory.  fd can be set
     to AT_FDCWD in order to specify the current directory.

     One of the owner or group id's may be left unchanged by specifying it as
     (uid_t)-1 or (gid_t)-1 respectively.


RETURN VALUES

     The chown(), lchown(), fchown(), and fchownat() functions return the
     value 0 if successful; otherwise the value -1 is returned and the global
     variable errno is set to indicate the error.


ERRORS

     chown(), lchown() and fchownat() will fail and the file will be unchanged
     if:

     [EACCES]           Search permission is denied for a component of the
                        path prefix.

     [EFAULT]           path points outside the process's allocated address
                        space.

     [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 the pathname.

     [ENAMETOOLONG]     A component of a pathname exceeded {NAME_MAX} charac-
                        ters, or an entire path name exceeded {PATH_MAX} char-
                        acters.

     [ENOENT]           The named file does not exist.

     [ENOTDIR]          A component of the path prefix is not a directory.

     [EPERM]            The effective user ID is not the super-user.

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

     In addition, fchownat() will fail if:

     [EBADF]            path does not specify an absolute path and fd is nei-
                        ther AT_FDCWD nor a valid file descriptor open for
                        reading or searching.

     [ENOTDIR]          path is not an absolute path and fd is a file descrip-
                        tor associated with a non-directory file.

     fchown() will fail if:

     [EBADF]            fd does not refer to a valid descriptor.

     [EINVAL]           fd refers to a socket, not a file.

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

     [EPERM]            The effective user ID is not the super-user.

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


SEE ALSO

     chgrp(1), chmod(2), flock(2), symlink(7), chown(8)


STANDARDS

     The chown() function deviates from the semantics defined in ISO/IEC
     9945-1:1990 (``POSIX.1''), which specifies that, unless the caller is the
     super-user, both the set-user-id and set-group-id bits on a file shall be
     cleared, regardless of the file attribute changed.  The lchown() and
     fchown() functions, as defined by X/Open Portability Guide Issue 4,
     Version 2 (``XPG4.2''), provide the same semantics.  fchownat() conforms
     to IEEE Std 1003.1-2008 (``POSIX.1'').

     To retain conformance to these standards, compatibility interfaces are
     provided by the POSIX Compatibility Library (libposix, -lposix) as fol-
     lows:
     ·   The chown() function conforms to ISO/IEC 9945-1:1990 (``POSIX.1'')
         and X/Open Portability Guide Issue 4, Version 2 (``XPG4.2'').
     ·   The lchown() and fchown() functions conform to X/Open Portability
         Guide Issue 4, Version 2 (``XPG4.2'').


HISTORY

     The chown() function call appeared in Version 1 AT&T UNIX.  The fchown()
     function call appeared in 4.2BSD.

     The chown() and fchown() functions were changed to follow symbolic links
     in 4.4BSD.  The lchown() function call appeared in NetBSD 1.3.

NetBSD 9.4_STABLE              September 1, 2019             NetBSD 9.4_STABLE