.\" $NetBSD: chown.2,v 1.36.28.1 2019/09/05 08:19:40 martin Exp $ .\" .\" Copyright (c) 1980, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)chown.2 8.4 (Berkeley) 4/19/94 .\" .Dd September 1, 2019 .Dt CHOWN 2 .Os .Sh NAME .Nm chown , .Nm lchown , .Nm fchown , .Nm fchownat .Nd change owner and group of a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn chown "const char *path" "uid_t owner" "gid_t group" .Ft int .Fn lchown "const char *path" "uid_t owner" "gid_t group" .Ft int .Fn fchown "int fd" "uid_t owner" "gid_t group" .In fcntl.h .Ft int .Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" .Sh DESCRIPTION The owner ID and group ID of the file named by .Fa path or referenced by .Fa fd is changed as specified by the arguments .Fa owner and .Fa group . The owner of a file may change the .Fa group to a group of which he or she is a member, but the change .Fa owner capability is restricted to the super-user. .Pp When called to change the owner of a file, .Fn chown , .Fn lchown and .Fn fchown clear the set-user-id .Dv ( S_ISUID ) bit on the file. When a called to change the group of a file, .Fn chown , .Fn lchown and .Fn fchown clear the set-group-id .Dv ( 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. .Pp .Fn lchown is like .Fn chown except in the case where the named file is a symbolic link, in which case .Fn lchown changes the owner and group of the link, while .Fn chown changes the owner and group of the file the link references. .Pp .Fn fchown is particularly useful when used in conjunction with the file locking primitives (see .Xr flock 2 ) . .Pp .Fn fchownat works the same way as .Fn chown (or .Fn lchown if .Dv AT_SYMLINK_NOFOLLOW is set in .Fa flag ) except if .Fa path is relative. In that case, it is looked up from a directory whose file descriptor was passed as .Fa fd . Search permission is required on this directory. .\" (These alternatives await a decision about the semantics of O_SEARCH) .\" Search permission is required on this directory .\" except if .\" .Fa fd .\" was opened with the .\" .Dv O_SEARCH .\" flag. .\" - or - .\" This file descriptor must have been opened with the .\" .Dv O_SEARCH .\" flag. .Fa fd can be set to .Dv AT_FDCWD in order to specify the current directory. .Pp One of the owner or group id's may be left unchanged by specifying it as (uid_t)\-1 or (gid_t)\-1 respectively. .Sh RETURN VALUES .Rv -std chown lchown fchown fchownat .Sh ERRORS .Fn chown , .Fn lchown and .Fn fchownat will fail and the file will be unchanged if: .Bl -tag -width Er .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EFAULT .Fa path points outside the process's allocated address space. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er ENAMETOOLONG A component of a pathname exceeded .Brq Dv NAME_MAX characters, or an entire path name exceeded .Brq Dv PATH_MAX characters. .It Bq Er ENOENT The named file does not exist. .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er EPERM The effective user ID is not the super-user. .It Bq Er EROFS The named file resides on a read-only file system. .El .Pp In addition, .Fn fchownat will fail if: .Bl -tag -width Er .It Bq Er EBADF .Fa path does not specify an absolute path and .Fa fd is neither .Dv AT_FDCWD nor a valid file descriptor open for reading or searching. .It Bq Er ENOTDIR .Fa path is not an absolute path and .Fa fd is a file descriptor associated with a non-directory file. .El .Pp .Fn fchown will fail if: .Bl -tag -width Er .It Bq Er EBADF .Fa fd does not refer to a valid descriptor. .It Bq Er EINVAL .Fa fd refers to a socket, not a file. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .It Bq Er EPERM The effective user ID is not the super-user. .It Bq Er EROFS The named file resides on a read-only file system. .El .Sh SEE ALSO .Xr chgrp 1 , .Xr chmod 2 , .Xr flock 2 , .Xr symlink 7 , .Xr chown 8 .Sh STANDARDS The .Fn chown function deviates from the semantics defined in .St -p1003.1-90 , 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 .Fn lchown and .Fn fchown functions, as defined by .St -xpg4.2 , provide the same semantics. .Fn fchownat conforms to .St -p1003.1-2008 . .Pp To retain conformance to these standards, compatibility interfaces are provided by the .Lb libposix as follows: .Bl -bullet -compact .It The .Fn chown function conforms to .St -p1003.1-90 and .St -xpg4.2 . .It The .Fn lchown and .Fn fchown functions conform to .St -xpg4.2 . .El .Sh HISTORY The .Fn chown function call appeared in .At v1 . The .Fn fchown function call appeared in .Bx 4.2 . .Pp The .Fn chown and .Fn fchown functions were changed to follow symbolic links in .Bx 4.4 . The .Fn lchown function call appeared in .Nx 1.3 .