unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

CHOWN(2)                    BSD System Calls Manual                   CHOWN(2)

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

SYNOPSIS
     #include <&lt;unistd.h>&gt;

     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 <&lt;fcntl.h>&gt;
     #include <&lt;unistd.h>&gt;

     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 (or link) named by path or refer-
     enced 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 superuser.

     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 sym-
     bolic 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 behav-
     ior is identical to a call to chown() or lchown(), depending on whether
     or not the AT_SYMLINK_NOFOLLOW bit is set in flag.

     The flag argument is the bitwise OR of zero or more of the following val-
     ues:

           AT_SYMLINK_NOFOLLOW  If path names a symbolic link, then the owner-
                                ship 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
     -1.

RETURN VALUES
     Upon successful completion, the value 0 is returned; 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 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 charac-
                        ters, or an entire pathname (including the terminating
                        NUL) exceeded PATH_MAX bytes.

     [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 translat-
                        ing 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
                        space.

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

     Additionally, fchownat() will fail if:

     [EINVAL]           The value of the flag argument was neither zero nor
                        AT_SYMLINK_NOFOLLOW.

     [EBADF]            The path argument specifies a relative path and the fd
                        argument is neither AT_FDCWD nor a valid file descrip-
                        tor.

     [ENOTDIR]          The path argument specifies a relative path and the fd
                        argument is a valid file descriptor but it does not
                        reference a directory.

     [EACCES]           The path argument specifies a relative path but search
                        permission is denied for the directory which the fd
                        file descriptor references.

     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.

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

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

HISTORY
     The 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.1cBSD.

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

     The fchownat() system call has been available since OpenBSD 5.0.

BSD                            January 19, 2015                            BSD