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-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.