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 accidental 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
references.
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 translating the
pathname.
-
-
- [
ENAMETOOLONG
]
- A component of a pathname exceeded
{
NAME_MAX
} characters, or an entire path name
exceeded {PATH_MAX
} characters.
-
-
- [
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 neither
AT_FDCWD
nor a valid file descriptor open for
reading or searching.
-
-
- [
ENOTDIR
]
- path is not an absolute path and
fd is a file descriptor 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
IEEE Std 1003.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 follows:
- The
chown() function conforms to IEEE Std
1003.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
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.