Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
CHOWN(2)                  FreeBSD System Calls Manual                 CHOWN(2)

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

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

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

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

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

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

     The owner ID and group ID of the file (or link) 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

     By default, chown() clears the set-user-ID and set-group-ID bits on the
     file to prevent accidental or mischievous creation of set-user-ID and
     set-group-ID programs.  This behaviour can be overridden by setting the
     sysctl(8) variable fs.posix.setuid to zero.

     lchown() operates similarly to how chown() operated on older systems, and
     does not follow symbolic links.  It allows the owner and group of a
     symbolic link to be set.

     The fchownat() function is equivalent to either the chown() or lchown()
     function depending on the value of flag (see below), except that where
     path specifies a relative path, the file whose ownership is changed is
     determined relative to the directory associated with file descriptor fd
     instead of the current working directory.

     If fchownat() is passed the special value AT_FDCWD (defined in <fcntl.h>)
     in the fd parameter, the current working directory is used and the
     behavior is identical to a call to chown() or lchown(), depending on
     whether or not the AT_SYMLINK_NOFOLLOW bit is set in flag.

     Values for flag are constructed by bitwise-inclusive ORing flags from the
     following list defined in <fcntl.h>:

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

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

     One of the owner or group IDs may be left unchanged by specifying it as

     Zero is returned if the operation was successful; -1 is returned if an
     error occurs, with a more specific error code being placed in the global
     variable errno.

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

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

     [ENAMETOOLONG]     A component of a pathname exceeded {NAME_MAX}
                        characters, or an entire path name exceeded {PATH_MAX}

     [ENOENT]           The named file does not exist.

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

     [ELOOP]            Too many symbolic links were encountered in
                        translating the pathname.

     [EPERM]            The effective user ID is not the superuser.

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

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

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

     Additionally, fchownat() will fail if:

     [EBADF]            The path argument does not specify an absolute path
                        and the fd argument is neither AT_FDCWD nor a valid
                        file descriptor open for reading.

     fchown() will fail if:

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

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

     [EPERM]            The effective user ID is not the superuser.

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

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

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

     The chown(), fchown(), fchownat(), and lchown() functions are expected to
     conform to IEEE Std 1003.1-2008 (``POSIX.1'').

     A chown() system call first appeared in Version 1 AT&T UNIX.  Since
     Version 6 AT&T UNIX it supports changing the group as well, and in
     Version 7 AT&T UNIX group was made a separate argument.

     The fchown() system call first appeared in 4.2BSD.

     The chown() and fchown() functions were changed to follow symbolic links
     in 4.4BSD; therefore, and for compatibility with AT&T System V Release 4
     UNIX, the lchown() function was added to OpenBSD 2.1.

     The fchownat() function appeared in OpenBSD 5.0.

FreeBSD 11.0-PRERELEASE        November 7, 2011        FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help