diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/chown.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/chown.1p | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/chown.1p b/man-pages-posix-2017/man1p/chown.1p new file mode 100644 index 0000000..82ba02d --- /dev/null +++ b/man-pages-posix-2017/man1p/chown.1p @@ -0,0 +1,303 @@ +'\" et +.TH CHOWN "1P" 2017 "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 +\(em change the file ownership +.SH SYNOPSIS +.LP +.nf +chown \fB[\fR-h\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR... +.P +chown -R \fB[\fR-H|-L|-P\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR chown +utility shall set the user ID of the file named by each +.IR file +operand to the user ID specified by the +.IR owner +operand. +.P +For each +.IR file +operand, or, if the +.BR \-R +option is used, each file encountered while walking the directory +trees specified by the +.IR file +operands, the +.IR chown +utility shall perform actions equivalent to the +\fIchown\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017, called with the following arguments: +.IP " 1." 4 +The +.IR file +operand shall be used as the +.IR path +argument. +.IP " 2." 4 +The user ID indicated by the +.IR owner +portion of the first operand shall be used as the +.IR owner +argument. +.IP " 3." 4 +If the +.IR group +portion of the first operand is given, the group ID indicated by it +shall be used as the +.IR group +argument; otherwise, the group ownership shall not be changed. +.P +Unless +.IR chown +is invoked by a process with appropriate privileges, the set-user-ID +and set-group-ID bits of a regular file shall be cleared upon +successful completion; the set-user-ID and set-group-ID bits of other +file types may be cleared. +.SH OPTIONS +The +.IR chown +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\-h\fP" 10 +For each file operand that names a file of type symbolic link, +.IR chown +shall attempt to set the user ID of the symbolic link. If a group ID +was specified, for each file operand that names a file of +type symbolic link, +.IR chown +shall attempt to set the group ID of the symbolic link. +.IP "\fB\-H\fP" 10 +If the +.BR \-R +option is specified and a symbolic link referencing a file of type +directory is specified on the command line, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +referenced by the symbolic link and all files in the file hierarchy +below it. +.IP "\fB\-L\fP" 10 +If the +.BR \-R +option is specified and a symbolic link referencing a file of type +directory is specified on the command line or encountered during the +traversal of a file hierarchy, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +referenced by the symbolic link and all files in the file hierarchy +below it. +.IP "\fB\-P\fP" 10 +If the +.BR \-R +option is specified and a symbolic link is specified on the command +line or encountered during the traversal of a file hierarchy, +.IR chown +shall change the owner ID (and group ID, if specified) of the symbolic +link. The +.IR chown +utility shall not follow the symbolic link to any other part of the +file hierarchy. +.IP "\fB\-R\fP" 10 +Recursively change file user and group IDs. For each +.IR file +operand that names a directory, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +and all files in the file hierarchy below it. Unless a +.BR \-H , +.BR \-L , +or +.BR \-P +option is specified, it is unspecified which of these options will be +used as the default. +.P +Specifying more than one of the mutually-exclusive options +.BR \-H , +.BR \-L , +and +.BR \-P +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIowner\fB[\fR:\fIgroup\fB]\fR" 10 +A user ID and optional group ID to be assigned to +.IR file . +The +.IR owner +portion of this operand shall be a user name from the user database or +a numeric user ID. Either specifies a user ID which shall be given to +each file named by one of the +.IR file +operands. If a numeric +.IR owner +operand exists in the user database as a user name, the user ID number +associated with that user name shall be used as the user ID. Similarly, +if the +.IR group +portion of this operand is present, it shall be a group name from the +group database or a numeric group ID. Either specifies a group ID which +shall be given to each file. If a numeric group operand exists in the +group database as a group name, the group ID number associated with +that group name shall be used as the group ID. +.IP "\fIfile\fR" 10 +A pathname of a file whose user ID is to be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chown : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.P +Some implementations restrict the use of +.IR chown +to a user with appropriate privileges. +.SH EXAMPLES +None. +.SH RATIONALE +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. These are masked by specifying only +0 and >0 as exit values. +.P +The functionality of +.IR chown +is described substantially through references to functions in the +System Interfaces volume of POSIX.1\(hy2017. In this way, there is no duplication of effort required for +describing the interactions of permissions, multiple groups, and so +on. +.P +The 4.3 BSD method of specifying both owner and group was included in +\&this volume of POSIX.1\(hy2017 because: +.IP " *" 4 +There are cases where the desired end condition could not be achieved +using the +.IR chgrp +and +.IR chown +(that only changed the user ID) utilities. (If the current owner is not +a member of the desired group and the desired owner is not a member of +the current group, the +\fIchown\fR() +function could fail unless both owner and group are changed at the same +time.) +.IP " *" 4 +Even if they could be changed independently, in cases where both are +being changed, there is a 100% performance penalty caused by being +forced to invoke both utilities. +.P +The BSD syntax +.IR user [.\c +.IR group ] +was changed to +.IR user [:\c +.IR group ] +in this volume of POSIX.1\(hy2017 because the +<period> +is a valid character in login names (as specified by the Base Definitions volume of POSIX.1\(hy2017, login +names consist of characters in the portable filename character set). The +<colon> +character was chosen as the replacement for the +<period> +character because it would never be allowed as a character in a user +name or group name on historical implementations. +.P +The +.BR \-R +option is considered by some observers as an undesirable departure from +the historical UNIX system tools approach; since a tool, +.IR find , +already exists to recurse over directories, there seemed to be no good +reason to require other tools to have to duplicate that functionality. +However, the +.BR \-R +option was deemed an important user convenience, is far more efficient +than forking a separate process for each element of the directory +hierarchy, and is in widespread historical use. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchgrp\fR\^", +.IR "\fIchmod\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIchown\fR\^(\|)" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +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.opengroup.org/unix/online.html . +.PP +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 . |