'\"macro stdmacro
.if n .pH g2.chown $W% of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} chown 2 "" "\&"
.if \nX=1 .ds x} chown 2 ""
.if \nX=2 .ds x} chown 2 "" "\&"
.if \nX=3 .ds x} chown "" "" "\&"
.TH \*(x}
.SH NAME
\f4chown\f1, \f4lchown\f1, \f4fchown\f1 \- change owner and group of a file
.SH SYNOPSIS
\f4#include <unistd.h>\f1
.br
\f4#include <sys/stat.h>\f1
.PP
\f4int chown(const char \(**path, uid_t owner, gid_t group); \f1
.PP
\f4int lchown(const char \(**path, uid_t owner, gid_t group); \f1
.PP
\f4int fchown(int fildes, uid_t owner, gid_t group);\f1
.SH DESCRIPTION
The owner
.SM ID
and group
.SM ID
of the file specified by \f2path\f1 or 
referenced by the descriptor \f2fildes\f1, are set to \f2owner\f1 and
\f2group\fP respectively.  If
.I owner
or
.I group
is specified as \-1, the corresponding
.SM ID
of the file is not changed.
.PP
The function \f4lchown\fP sets the owner
.SM ID
and group
.SM ID
of the
named file just as \f4chown\fP does, except in the case where
the named file is a symbolic link.
In this case \f4lchown\fP changes the ownership of the symbolic link
file itself, while \f4chown\fP changes the ownership of the file
or directory to which the symbolic link refers.
.PP
If \f4chown\fP, \f4lchown\fP, or \f4fchown\fP is invoked by
a process other than super-user,
the set-user-\s-1ID\s0 and set-group-\s-1ID\s0 bits of the file mode,
\f4S_ISUID\fP and \f4S_ISGID\fP respectively, are cleared [see \f4chmod\fP(2)].
.PP
The operating system has a configuration option, {\f4_POSIX_CHOWN_RESTRICTED\f1},
to restrict
ownership changes for the \f4chown\fP, \f4lchown\fP, and \f4fchown\fP system calls.
When {\f4_POSIX_CHOWN_RESTRICTED\f1} is not in effect,
the effective user
.SM ID
of the process must match the
owner of the file or the process must be the super-user to change the 
ownership of a file.
When {\f4_POSIX_CHOWN_RESTRICTED\f1} is in effect, the \f4chown\fP, \f4lchown\fP,
and \f4fchown\fP system calls,
for users other than super-user, prevent the owner of the
file from changing the owner
.SM ID
of the file and restrict the
change of the group of the file to the list of supplementary group
\s-1ID\s0s.
.PP
Upon successful completion, \f4chown\fP, \f4fchown\fP and \f4lchown\fP
mark for update the \f4st_ctime\fP field of the file.
.PP
\f4chown\fP
and \f4lchown\fP fail and the owner and group of the named file
remain unchanged if one or more of the following are true:
.TP 20
\f4EACCES\fP
Search permission is denied on a component of the path prefix of
.IR path .
.TP 20
\f4EFAULT\fP
.I path
points outside the allocated address space of the process.
.TP 20
\f4EINTR\fP
A signal was caught during the \f4chown\fP or \f4lchown\fP system calls.
.TP 20
\f4EINVAL\fP
\f2group\f1 or \f2owner\f1 is out of range.
.TP 20
\f4EIO\fP
An I/O error occurred while reading from or writing to the file system.
.TP 20
\f4ELOOP\fP
Too many symbolic links were encountered in translating \f2path\f1.
.TP 20
\f4EMULTIHOP\fP 
Components of
.I path
require hopping to multiple remote machines
and file system type does not allow it.
Too many symbolic links were encountered in translating
.IR path .
.TP 20
\f4ENAMETOOLONG\fP
The length of the \f2path\f1 argument exceeds {\f4PATH_MAX\f1}, or the
length of a \f2path\f1 component exceeds {\f4NAME_MAX\f1} while
\f4_POSIX_NO_TRUNC\f1 is in effect.
.TP 20
\f4ENOLINK\fP 
.I path 
points to a remote machine and the link to that machine is no longer
active.
.TP 20
\f4ENOTDIR\fP
A component of the path prefix of
.I path
is not a directory.
.TP 20
\f4ENOENT\fP
Either a component of the path prefix or the file referred to by
.I path
does not exist or is a null pathname.
.TP 20
\f4EPERM\fP
The effective user
.SM ID
does not match the owner of the file or the
process is not the super-user
and {\f4_POSIX_CHOWN_RESTRICTED\f1} indicates that such
privilege is required.
.TP 20
\f4EROFS\fP
The named file 
resides on a read-only file system.
.PP
\f4fchown\fP
fails and the owner and group of the named file remain
unchanged if one or more of the following are true:
.TP 20
\f4EBADF\fP
.I fildes
is not an open file descriptor.
.TP 20
\f4EINVAL\fP
\f2group\f1 or \f2owner\f1 is out of range.
.TP 20
\f4EPERM\fP
The effective user
.SM ID
does not match the owner of the file or the
process is not the super-user
and {\f4_POSIX_CHOWN_RESTRICTED\f1} indicates that such
privilege is required.
.TP 20
\f4EROFS\fP
The named file referred to by
.I fildes
resides on a read-only file system.
.TP 20
\f4EINTR\fP
A signal was caught during execution of the system call.
.TP 20
\f4EIO\fP
An I/O error occurred while reading from or writing to the file system.
.TP 20
\f4ENOLINK\fP 
.I fildes
points to a remote machine and the link to that machine is no longer
active.
.SH "SEE ALSO"
\f4chmod\fP(2).
.br
\f4chown\fP(1), \f4chgrp\fP(1) in the \f2User's Reference Manual\f1.
.SH DIAGNOSTICS
Upon successful completion, a value of 0 is returned.
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
