mirror of https://github.com/mkerrisk/man-pages
249 lines
6.9 KiB
Groff
249 lines
6.9 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
|
|
.\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl)
|
|
.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Modified by Michael Haardt <michael@moria.de>
|
|
.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified 1996-07-09 by Andries Brouwer <aeb@cwi.nl>
|
|
.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified 1997-05-18 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
|
|
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" 2007-07-08, mtk, added an example program; updated SYNOPSIS
|
|
.\"
|
|
.TH CHOWN 2 2007-07-26 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
chown, fchown, lchown \- change ownership of a file
|
|
.SH SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.sp
|
|
.BI "int chown(const char *" path ", uid_t " owner ", gid_t " group );
|
|
.br
|
|
.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
|
|
.br
|
|
.BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group );
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR fchown (),
|
|
.BR lchown ():
|
|
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
|
|
.SH DESCRIPTION
|
|
These system calls change the owner and group of the file specified by
|
|
.I path
|
|
or by
|
|
.IR fd .
|
|
Only a privileged process (Linux: one with the
|
|
.B CAP_CHOWN
|
|
capability) may change the owner of a file.
|
|
The owner of a file may change the group of the file
|
|
to any group of which that owner is a member.
|
|
A privileged process (Linux: with
|
|
.BR CAP_CHOWN )
|
|
may change the group arbitrarily.
|
|
|
|
If the
|
|
.I owner
|
|
or
|
|
.I group
|
|
is specified as \-1, then that ID is not changed.
|
|
|
|
When the owner or group of an executable file are changed by a non-superuser,
|
|
the
|
|
.B S_ISUID
|
|
and
|
|
.B S_ISGID
|
|
mode bits are cleared.
|
|
POSIX does not specify whether
|
|
this also should happen when root does the
|
|
.BR chown ();
|
|
the Linux behavior depends on the kernel version.
|
|
.\" In Linux 2.0 kernels, superuser was like everyone else
|
|
.\" In 2.2, up to 2.2.12, these bits were not cleared for superuser.
|
|
.\" Since 2.2.13, superuser is once more like everyone else.
|
|
In case of a non-group-executable file (with clear
|
|
.B S_IXGRP
|
|
bit)
|
|
the
|
|
.B S_ISGID
|
|
bit indicates mandatory locking, and is not cleared by a
|
|
.BR chown ().
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
Depending on the file system, other errors can be returned.
|
|
The more general errors for
|
|
.BR chown ()
|
|
are listed below.
|
|
.TP
|
|
.B EACCES
|
|
Search permission is denied on a component of the path prefix.
|
|
(See also
|
|
.BR path_resolution (7).)
|
|
.TP
|
|
.B EFAULT
|
|
.I path
|
|
points outside your accessible address space.
|
|
.TP
|
|
.B ELOOP
|
|
Too many symbolic links were encountered in resolving
|
|
.IR path .
|
|
.TP
|
|
.B ENAMETOOLONG
|
|
.I path
|
|
is too long.
|
|
.TP
|
|
.B ENOENT
|
|
The file does not exist.
|
|
.TP
|
|
.B ENOMEM
|
|
Insufficient kernel memory was available.
|
|
.TP
|
|
.B ENOTDIR
|
|
A component of the path prefix is not a directory.
|
|
.TP
|
|
.B EPERM
|
|
The calling process did not have the required permissions
|
|
(see above) to change owner and/or group.
|
|
.TP
|
|
.B EROFS
|
|
The named file resides on a read-only file system.
|
|
.PP
|
|
The general errors for
|
|
.BR fchown ()
|
|
are listed below:
|
|
.TP
|
|
.B EBADF
|
|
The descriptor is not valid.
|
|
.TP
|
|
.B EIO
|
|
A low-level I/O error occurred while modifying the inode.
|
|
.TP
|
|
.B ENOENT
|
|
See above.
|
|
.TP
|
|
.B EPERM
|
|
See above.
|
|
.TP
|
|
.B EROFS
|
|
See above.
|
|
.SH "CONFORMING TO"
|
|
4.4BSD, SVr4, POSIX.1-2001.
|
|
|
|
The 4.4BSD version can only be
|
|
used by the superuser (that is, ordinary users cannot give away files).
|
|
.\" chown():
|
|
.\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
|
|
.\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions.
|
|
.\" fchown():
|
|
.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
|
|
.\" error conditions.
|
|
.SH NOTES
|
|
The
|
|
.BR chown ()
|
|
semantics are deliberately violated on NFS file systems
|
|
which have UID mapping enabled.
|
|
Additionally, the semantics of all system
|
|
calls which access the file contents are violated, because
|
|
.BR chown ()
|
|
may cause immediate access revocation on already open files.
|
|
Client side
|
|
caching may lead to a delay between the time where ownership have
|
|
been changed to allow access for a user and the time where the file can
|
|
actually be accessed by the user on other clients.
|
|
|
|
In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
|
|
.BR chown ()
|
|
did not follow symbolic links.
|
|
Since Linux 2.1.81,
|
|
.BR chown ()
|
|
does follow symbolic links, and there is a new system call
|
|
.BR lchown ()
|
|
that does not follow symbolic links.
|
|
Since Linux 2.1.86, this new call (that has the same semantics
|
|
as the old
|
|
.BR chown ())
|
|
has got the same syscall number, and
|
|
.BR chown ()
|
|
got the newly introduced number.
|
|
.SH EXAMPLE
|
|
.PP
|
|
The following program changes the ownership of the file named in
|
|
its second command-line argument to the value specified in its
|
|
first command-line arguemnt.
|
|
The new owner can be specified either as a numeric user ID,
|
|
or as a username (which is converted to a user ID by using
|
|
.BR getpwnam (3)
|
|
to perform a lookup in the system password file).
|
|
.nf
|
|
|
|
#include <pwd.h>
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <unistd.h>
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
uid_t uid;
|
|
struct passwd *pwd;
|
|
char *endptr;
|
|
|
|
if (argc != 3 || argv[1][0] == '\\0') {
|
|
fprintf(stderr, "%s <owner> <file>\\n", argv[0]);
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
|
|
|
|
if (*endptr != '\\0') { /* Was not pure numeric string */
|
|
pwd = getpwnam(argv[1]); /* Try getting UID for username */
|
|
if (pwd == NULL) {
|
|
perror("getpwnam");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
uid = pwd\->pw_uid;
|
|
}
|
|
|
|
if (chown(argv[2], uid, \-1) == \-1) {
|
|
perror("chown");
|
|
exit(EXIT_FAILURE);
|
|
} /* if */
|
|
|
|
exit(EXIT_SUCCESS);
|
|
} /* main */
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR chmod (2),
|
|
.BR fchownat (2),
|
|
.BR flock (2),
|
|
.BR path_resolution (7)
|