path: root/usr/src/man/man1/chown.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\"
.TH CHOWN 1 "Jul 11, 2008"
.SH NAME
chown \- change file ownership
.SH SYNOPSIS
.SS "/usr/bin/chown"
.LP
.nf
\fB/usr/bin/chown\fR [\fB-fhR\fR] \fIowner\fR[:\fIgroup\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/chown\fR \fB-s\fR [\fB-fhR\fR] \fIownersid\fR[:\fIgroupsid\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/chown\fR \fB-R\fR [\fB-f\fR] [\fB-H\fR | \fB-L\fR | \fB-P\fR] \fIowner\fR[:\fIgroup\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/chown\fR \fB-s\fR \fB-R\fR [\fB-f\fR] [\fB-H\fR | \fB-L\fR | \fB-P\fR] \fIownersid\fR[:\fIgroupsid\fR] \fIfile\fR...
.fi

.SS "/usr/xpg4/bin/chown"
.LP
.nf
\fB/usr/xpg4/bin/chown\fR [\fB-fhR\fR] \fIowner\fR[:\fIgroup\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/chown\fR \fB-s\fR [\fB-fhR\fR] \fIownersid\fR[:\fIgroupsid\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/chown\fR \fB-R\fR [\fB-f\fR] [\fB-H\fR | \fB-L\fR | \fB-P\fR] \fIowner\fR[:\fIgroup\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/chown\fR \fB-s\fR \fB-R\fR [\fB-f\fR] [\fB-H\fR | \fB-L\fR | \fB-P\fR] \fIownersid\fR[:\fIgroupsid\fR] \fIfile\fR...
.fi

.SS "ksh93"
.LP
.nf
\fBchown\fR [\fB-cflhmnvHLPRX\fR] [\fB-r\fR \fIfile\fR] \fIowner\fR[:\fIgroup\fR] \fIfile\fR...
.fi

.SH DESCRIPTION
.SS "/usr/bin/chown and /usr/xpg4/bin/chown"
.sp
.LP
The \fBchown\fR utility sets the user \fBID\fR of the file named by each
\fBfile\fR to the user \fBID\fR specified by \fIowner\fR, and, optionally, sets
the group \fBID\fR to that specified by \fIgroup\fR.
.sp
.LP
If \fBchown\fR is invoked by other than the super-user, the set-user-\fBID\fR
bit is cleared.
.sp
.LP
Only the owner of a file (or the super-user) can change the owner of that file.
.sp
.LP
The operating system has a configuration option
\fB{_POSIX_CHOWN_RESTRICTED}\fR, to restrict ownership changes. When this
option is in effect the owner of the file is prevented from changing the owner
\fBID\fR of the file. Only the super-user can arbitrarily change owner
\fBID\fRs whether or not this option is in effect. To set this configuration
option, include the following line in \fB/etc/system\fR:
.sp
.in +2
.nf
\fBset rstchown = 1\fR
.fi
.in -2
.sp

.sp
.LP
To disable this option, include the following line in \fB/etc/system\fR:
.sp
.in +2
.nf
\fBset rstchown = 0\fR
.fi
.in -2
.sp

.sp
.LP
\fB{_POSIX_CHOWN_RESTRICTED}\fR is enabled by default. See \fBsystem\fR(4) and
\fBfpathconf\fR(2).
.SS "ksh93"
.sp
.LP
The \fBchown\fR built-in in \fBksh93\fR is associated with the \fB/bin\fR and
\fB/usr/bin\fR paths. It is invoked when \fBchown\fR is executed without a
pathname prefix and the pathname search finds a \fB/bin/chown\fR or
/usr/bin/chown executable.
.sp
.LP
\fBchown\fR changes the ownership of each file to \fIowner\fR. \fIowner\fR can
be specified as either a user name or a numeric user id. The group ownership of
each file can also be changed to \fIgroup\fR by appending \fI:group\fR to the
user name.
.SH OPTIONS
.SS "/usr/bin/chown and /usr/xpg4/bin/chown"
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
Force. Does not report errors.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 6n
If the file is a symbolic link, this option changes the owner of the symbolic
link. Without this option, the owner of the file referenced by the symbolic
link is changed.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR\fR
.ad
.RS 6n
If the file specified on the command line is a symbolic link referencing a file
of type directory, this option changes the owner of the directory referenced by
the symbolic link and all the files in the file hierarchy below it. If a
symbolic link is encountered when traversing a file hierarchy, the owner of the
target file is changed, but no recursion takes place.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 6n
If the file is a symbolic link, this option changes the owner of the file
referenced by the symbolic link. If the file specified on the command line, or
encountered during the traversal of the file hierarchy, is a symbolic link
referencing a file of type directory, then this option changes the owner of the
directory referenced by the symbolic link and all files in the file hierarchy
below it.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 6n
If the file specified on the command line or encountered during the traversal
of a file hierarchy is a symbolic link, this option changes the owner of the
symbolic link. This option does not follow the symbolic link to any other part
of the file hierarchy.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
The owner and/or group arguments are Windows SID strings. This option requires
a file system that supports storing SIDs, such as ZFS.
.RE

.sp
.LP
Specifying more than one of the mutually-exclusive options \fB-H\fR, \fB-L\fR,
or \fB-P\fR is not considered an error. The last option specified determines
the behavior of \fBchown\fR.
.SS "/usr/bin/chown"
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 6n
Recursive. \fBchown\fR descends through the directory, and any subdirectories,
setting the specified ownership \fBID\fR as it proceeds. When a symbolic link
is encountered, the owner of the target file is changed, unless the \fB-h\fR or
\fB-P\fR option is specified. However, no recursion takes place, unless the
\fB-H\fR or \fB-L\fR option is specified.
.RE

.SS "/usr/xpg4/bin/chown"
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 6n
Recursive. \fBchown\fR descends through the directory, and any subdirectories,
setting the specified ownership \fBID\fR as it proceeds. When a symbolic link
is encountered, the owner of the target file is changed, unless the \fB-h\fR or
\fB-P\fR option is specified. Unless the \fB-H\fR, \fB-L\fR, or \fB-P\fR option
is specified, the \fB-L\fR option is used as the default mode.
.RE

.SS "ksh93"
.sp
.LP
The following options are supported by the \fBksh93\fR built-in \fBchown\fR
command:
.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.br
.na
\fB\fB--changes\fR\fR
.ad
.sp .6
.RS 4n
Describe only files whose ownership actually changes.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.br
.na
\fB\fB--quiet | silent\fR\fR
.ad
.sp .6
.RS 4n
Do not report files whose ownership fails to change.
.RE

.sp
.ne 2
.na
\fB\fB-l | h\fR\fR
.ad
.br
.na
\fB\fB--symlink\fR\fR
.ad
.sp .6
.RS 4n
Change the ownership of the symbolic links on systems that support this option.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.br
.na
\fB\fB--map\fR\fR
.ad
.sp .6
.RS 4n
Interpret the first operand as a file that contains a map of:
.sp
.in +2
.nf
\fIfrom_uid\fR:\fIfrom_gid  to_uid:to_gid\fR
.fi
.in -2
.sp

pairs. Ownership of files matching the \fIfrom\fR part of any pair is changed
to the corresponding \fIto\fR part of the pair. The process stops at the first
match for each file. Unmatched files are silently ignored.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.br
.na
\fB\fB--show\fR\fR
.ad
.sp .6
.RS 4n
Show actions but do not execute.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.br
.na
\fB\fB--reference=file\fR\fR
.ad
.sp .6
.RS 4n
Omit the explicit ownership operand and use the ownership of the file instead.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.br
.na
\fB\fB--verbose\fR\fR
.ad
.sp .6
.RS 4n
Describe the changed permissions of all files.
.RE

.sp
.ne 2
.na
\fB\fB-H\fR\fR
.ad
.br
.na
\fB\fB--metaphysical\fR\fR
.ad
.sp .6
.RS 4n
Follow symbolic links for command arguments. Otherwise do not follow symbolic
links when traversing directories.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.br
.na
\fB\fB--logical | follow\fR\fR
.ad
.sp .6
.RS 4n
Follow symbolic links when traversing directories.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.br
.na
\fB\fB--physical | nofollow\fR\fR
.ad
.sp .6
.RS 4n
Do not follow symbolic links when traversing directories.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.br
.na
\fB\fB--recursive\fR\fR
.ad
.sp .6
.RS 4n
Recursively change ownership of directories and their contents.
.RE

.sp
.ne 2
.na
\fB\fB-X\fR\fR
.ad
.br
.na
\fB\fB--test\fR\fR
.ad
.sp .6
.RS 4n
Canonicalize output for testing.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIowner\fR[\fB:\fR\fIgroup\fR]\fR
.ad
.RS 17n
A user \fBID\fR and optional group \fBID\fR to be assigned to \fBfile\fR. The
\fIowner\fR portion of this operand must be a user name from the user database
or a numeric user \fBID\fR. Either specifies a user \fBID\fR to be given to
each file named by \fIfile\fR. If a numeric \fIowner\fR exists in the user
database as a user name, the user \fBID\fR number associated with that user
name is used as the user \fBID\fR. Similarly, if the \fIgroup\fR portion of
this operand is present, it must be a group name from the group database or a
numeric group \fBID\fR. Either specifies a group \fBID\fR to be given to each
file. If a numeric group operand exists in the group database as a group name,
the group \fBID\fR number associated with that group name is used as the group
\fBID\fR.
.RE

.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 17n
A path name of a file whose user \fBID\fR is to be modified.
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBchown\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH EXAMPLES
.LP
\fBExample 1 \fRChanging Ownership of All Files in the Hierarchy
.sp
.LP
The following command changes ownership of all files in the hierarchy,
including symbolic links, but not the targets of the links:

.sp
.in +2
.nf
example% \fBchown \(miR \(mih \fIowner\fR[:group] \fIfile\fR...\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBchown\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
The utility executed successfully and all requested changes were made.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/passwd\fR\fR
.ad
.RS 15n
System password file
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SS "/usr/bin/chown"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled. See NOTES.
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SS "/usr/xpg4/bin/chown"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled. See \fBNOTES\fR.
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SS "ksh93"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The \fBksh93\fR built-in binding to \fB/bin\fR and \fB/usr/bin\fR is Volatile.
The built-in interfaces are Uncommitted.
.SH SEE ALSO
.sp
.LP
\fBchgrp\fR(1), \fBchmod\fR(1), \fBksh93\fR(1), \fBchown\fR(2),
\fBfpathconf\fR(2), \fBpasswd\fR(4), \fBsystem\fR(4), \fBattributes\fR(5),
\fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
\fBchown\fR is \fBCSI\fR-enabled except for the \fIowner\fR and \fIgroup\fR
names.