'\" et

.TH CHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

chown, fchownat

\(em change owner and group of a file relative to directory

file descriptor

.SH SYNOPSIS

.LP

.nf

#include <unistd.h>

.P

int chown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP);

int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP,

    int \fIflag\fP);

.fi

.SH DESCRIPTION

The

\fIchown\fR()

function shall change the user and group ownership of a file.

.P

The

.IR path

argument points to a pathname naming a file. The user ID and group ID

of the named file shall be set to the numeric values contained in

.IR owner

and

.IR group ,

respectively.

.P

Only processes with an effective user ID equal to the user ID of the

file or with appropriate privileges may change the ownership of a

file. If _POSIX_CHOWN_RESTRICTED is in effect for

.IR path :

.IP " *" 4

Changing the user ID is restricted to processes with appropriate

privileges.

.IP " *" 4

Changing the group ID is permitted to a process with an effective user

ID equal to the user ID of the file, but without appropriate

privileges, if and only if

.IR owner

is equal to the file's user ID or (\c

.BR uid_t )\(mi1

and

.IR group

is equal either to the calling process' effective group ID or to one of

its supplementary group IDs.

.P

If the specified file is a regular file, one or more of the S_IXUSR,

S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does

not have appropriate privileges, the set-user-ID (S_ISUID) and

set-group-ID (S_ISGID) bits of the file mode shall be cleared upon

successful return from

\fIchown\fR().

If the specified file is a regular file, one or more of the S_IXUSR,

S_IXGRP, or S_IXOTH bits of the file mode are set, and the process has

appropriate privileges, it is implementation-defined whether the

set-user-ID and set-group-ID bits are altered. If the

\fIchown\fR()

function is successfully invoked on a file that is not a regular file

and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file

mode are set, the set-user-ID and set-group-ID bits may be cleared.

.P

If

.IR owner

or

.IR group

is specified as (\c

.BR uid_t )\(mi1

or (\c

.BR gid_t )\(mi1,

respectively, the corresponding ID of the file shall not be changed.

If both owner and group are \(mi1, the times need not be updated.

.P

Upon successful completion,

\fIchown\fR()

shall mark for update the last file status change timestamp of the file.

.P

The

\fIfchownat\fR()

function shall be equivalent to the

\fIchown\fR()

and

\fIlchown\fR()

functions except in the case where

.IR path

specifies a relative path. In this case the file to be changed is

determined relative to the directory associated with the file

descriptor

.IR fd

instead of the current working directory. If the file descriptor was

opened without O_SEARCH, the function shall check whether directory

searches are permitted using the current permissions of the directory

underlying the file descriptor. If the file descriptor was opened with

O_SEARCH, the function shall not perform the check.

.P

Values for

.IR flag

are constructed by a bitwise-inclusive OR of flags from the following

list, defined in

.IR <fcntl.h> :

.IP AT_SYMLINK_NOFOLLOW 6

.br

If

.IR path

names a symbolic link, ownership of the symbolic link is changed.

.P

If

\fIfchownat\fR()

is passed the special value AT_FDCWD in the

.IR fd

parameter, the current working directory shall be used and the behavior

shall be identical to a call to

\fIchown\fR()

or

\fIlchown\fR()

respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit

is set in the

.IR flag

argument.

.SH "RETURN VALUE"

Upon successful completion, these functions shall return 0.

Otherwise, these functions shall return \(mi1 and set

.IR errno

to indicate the error. If \(mi1 is returned, no changes are

made in the user ID and group ID of the file.

.SH ERRORS

These functions shall fail if:

.TP

.BR EACCES

Search permission is denied on a component of the path prefix.

.TP

.BR ELOOP

A loop exists in symbolic links encountered during resolution of the

.IR path

argument.

.TP

.BR ENAMETOOLONG

.br

The length of a component of a pathname is longer than

{NAME_MAX}.

.TP

.BR ENOENT

A component of

.IR path

does not name an existing file or

.IR path

is an empty string.

.TP

.BR ENOTDIR

A component of the path prefix names an existing file that is neither

a directory nor a symbolic link to a directory, or the

.IR path

argument contains at least one non-\c

<slash>

character and ends with one or more trailing

<slash>

characters and the last pathname component names an existing file

that is neither a directory nor a symbolic link to a directory.

.TP

.BR EPERM

The effective user ID does not match the owner of the file, or the

calling process does not have appropriate privileges and

_POSIX_CHOWN_RESTRICTED indicates that such privilege is required.

.TP

.BR EROFS

The named file resides on a read-only file system.

.P

The

\fIfchownat\fR()

function shall fail if:

.TP

.BR EACCES

.IR fd

was not opened with O_SEARCH and the permissions of the directory

underlying

.IR fd

do not permit directory searches.

.TP

.BR EBADF

The

.IR path

argument does not specify an absolute path and the

.IR fd

argument is neither AT_FDCWD nor a valid file descriptor open

for reading or searching.

.TP

.BR ENOTDIR

The

.IR path

argument is not an absolute path and

.IR fd

is a file descriptor associated with a non-directory file.

.P

These functions may fail if:

.TP

.BR EIO

An I/O error occurred while reading or writing to the file system.

.TP

.BR EINTR

The

\fIchown\fR()

function was interrupted by a signal which was caught.

.TP

.BR EINVAL

The owner or group ID supplied is not a value supported by the

implementation.

.TP

.BR ELOOP

More than

{SYMLOOP_MAX}

symbolic links were encountered during resolution of the

.IR path

argument.

.TP

.BR ENAMETOOLONG

.br

The length of a pathname exceeds

{PATH_MAX},

or pathname resolution of a symbolic link produced an intermediate

result with a length that exceeds

{PATH_MAX}.

.br

.P

The

\fIfchownat\fR()

function may fail if:

.TP

.BR EINVAL

The value of the

.IR flag

argument is not valid.

.LP

.IR "The following sections are informative."

.SH EXAMPLES

None.

.SH "APPLICATION USAGE"

Although

\fIchown\fR()

can be used on some implementations by the file owner to change the owner

and group to any desired values, the only portable use of this function

is to change the group of a file to the effective GID of the calling

process or to a member of its group set.

.SH RATIONALE

System III and System V allow a user to give away files;

that is, the owner of a file may change its user ID to anything. This

is a serious problem for implementations that are intended to meet

government security regulations.

Version 7 and 4.3 BSD permit only the superuser

to change the user ID of a file. Some government agencies (usually not

ones concerned directly with security) find this limitation too

confining. This volume of POSIX.1\(hy2008 uses \fImay\fP to permit secure implementations

while not disallowing System V.

.P

System III and System V allow the owner of a file to change the

group ID to anything. Version 7 permits only the superuser to change

the group ID of a file.

4.3 BSD permits the owner to change the group ID of a file

to its effective group ID

or to any of the groups in the list of supplementary group IDs, but to

no others.

.P

The POSIX.1\(hy1990 standard requires that the

\fIchown\fR()

function invoked by a non-appropriate privileged process clear the

S_ISGID and the S_ISUID bits for regular files, and permits them to be

cleared for other types of files. This is so that changes in

accessibility do not accidentally cause files to become security holes.

Unfortunately, requiring these bits to be cleared on non-executable

data files also clears the mandatory file locking bit (shared with

S_ISGID), which is an extension on many implementations (it first

appeared in System V). These bits should only be required to be

cleared on regular files that have one or more of their execute bits

set.

.P

The purpose of the

\fIfchownat\fR()

function is to enable changing ownership of files in directories other

than the current working directory without exposure to race

conditions. Any part of the path of a file could be changed in

parallel to a call to

\fIchown\fR()

or

\fIlchown\fR(),

resulting in unspecified behavior. By opening a file descriptor for

the target directory and using the

\fIfchownat\fR()

function it can be guaranteed that the changed file is located relative

to the desired directory.

.SH "FUTURE DIRECTIONS"

None.

.SH "SEE ALSO"

.IR "\fIchmod\fR\^(\|)",

.IR "\fIfpathconf\fR\^(\|)",

.IR "\fIlchown\fR\^(\|)"

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "\fB<fcntl.h>\fP",

.IR "\fB<sys_types.h>\fP",

.IR "\fB<unistd.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the

event of any discrepancy between this version and the original IEEE and

The Open Group Standard, the original IEEE and The Open Group Standard

is the referee document. The original Standard can be obtained online at

http://www.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .