lchown(2)
- NetBSD Manual Pages
CHOWN(2) NetBSD System Calls Manual CHOWN(2)
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 acci-
dental 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 ref-
erences.
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 translat-
ing the pathname.
[ENAMETOOLONG] A component of a pathname exceeded {NAME_MAX} charac-
ters, or an entire path name exceeded {PATH_MAX} char-
acters.
[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 nei-
ther AT_FDCWD nor a valid file descriptor open for
reading or searching.
[ENOTDIR] path is not an absolute path and fd is a file descrip-
tor 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 ISO/IEC
9945-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 fol-
lows:
· The chown() function conforms to ISO/IEC 9945-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 chown() function call appeared in Version 1 AT&T UNIX. 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.
NetBSD 9.4_STABLE September 1, 2019 NetBSD 9.4_STABLE
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.