diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/chmod.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/chmod.1p | 493 |
1 files changed, 493 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/chmod.1p b/man-pages-posix-2003/man1p/chmod.1p new file mode 100644 index 0000000..9a80533 --- /dev/null +++ b/man-pages-posix-2003/man1p/chmod.1p @@ -0,0 +1,493 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHMOD" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chmod +.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 +chmod \- change the file modes +.SH SYNOPSIS +.LP +\fBchmod\fP \fB[\fP\fB-R\fP\fB]\fP \fImode file\fP \fB...\fP +.SH DESCRIPTION +.LP +The \fIchmod\fP utility shall change any or all of the file mode bits +of the file named by each \fIfile\fP operand in the way +specified by the \fImode\fP operand. +.LP +It is implementation-defined whether and how the \fIchmod\fP utility +affects any alternate or additional file access control +mechanism (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Section 4.4, File Access Permissions) being used for the specified +file. +.LP +Only a process whose effective user ID matches the user ID of the +file, or a process with the appropriate privileges, shall be +permitted to change the file mode bits of a file. +.SH OPTIONS +.LP +The \fIchmod\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-R\fP +Recursively change file mode bits. For each \fIfile\fP operand that +names a directory, \fIchmod\fP shall change the file mode +bits of the directory and all files in the file hierarchy below it. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fImode\fP +Represents the change to be made to the file mode bits of each file +named by one of the \fIfile\fP operands; see the EXTENDED +DESCRIPTION section. +.TP 7 +\fIfile\fP +A pathname of a file whose file mode bits shall be modified. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIchmod\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +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). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +The \fImode\fP operand shall be either a \fIsymbolic_mode\fP expression +or a non-negative octal integer. The +\fIsymbolic_mode\fP form is described by the grammar later in this +section. +.LP +Each \fBclause\fP shall specify an operation to be performed on the +current file mode bits of each \fIfile\fP. The operations +shall be performed on each \fIfile\fP in the order in which the \fBclause\fPs +are specified. +.LP +The \fBwho\fP symbols \fBu\fP, \fBg\fP, and \fBo\fP shall specify +the \fIuser\fP, \fIgroup\fP, and \fIother\fP parts of +the file mode bits, respectively. A \fBwho\fP consisting of the symbol +\fBa\fP shall be equivalent to \fBugo\fP. +.LP +The \fBperm\fP symbols \fBr\fP, \fBw\fP, and \fBx\fP represent the +\fIread\fP, \fIwrite\fP, and \fIexecute\fP/ +\fIsearch\fP portions of file mode bits, respectively. The \fBperm\fP +symbol \fBs\fP shall represent the +\fIset-user-ID-on-execution\fP (when \fBwho\fP contains or implies +\fBu\fP) and \fIset-group-ID-on-execution\fP (when +\fBwho\fP contains or implies \fBg\fP) bits. +.LP +The \fBperm\fP symbol \fBX\fP shall represent the execute/search portion +of the file mode bits if the file is a directory or +if the current (unmodified) file mode bits have at least one of the +execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be +ignored if the file is not a directory and none of the execute bits +are set in the current file mode bits. +.LP +The \fBpermcopy\fP symbols \fBu\fP, \fBg\fP, and \fBo\fP shall represent +the current permissions associated with the user, +group, and other parts of the file mode bits, respectively. For the +remainder of this section, \fBperm\fP refers to the +non-terminals \fBperm\fP and \fBpermcopy\fP in the grammar. +.LP +If multiple \fBactionlist\fPs are grouped with a single \fBwholist\fP +in the grammar, each \fBactionlist\fP shall be applied +in the order specified with that \fBwholist\fP. The \fIop\fP symbols +shall represent the operation performed, as follows: +.TP 7 +\fB+\fP +If \fBperm\fP is not specified, the \fB'+'\fP operation shall not +change the file mode bits. +.LP +If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP +for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation +mask of the invoking process, shall be set. +.LP +Otherwise, the file mode bits represented by the specified \fBwho\fP +and \fBperm\fP values shall be set. +.TP 7 +\fB-\fP +If \fBperm\fP is not specified, the \fB'-'\fP operation shall not +change the file mode bits. +.LP +If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP +for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation +mask of the invoking process, shall be cleared. +.LP +Otherwise, the file mode bits represented by the specified \fBwho\fP +and \fBperm\fP values shall be cleared. +.TP 7 +\fB=\fP +Clear the file mode bits specified by the \fBwho\fP value, or, if +no \fBwho\fP value is specified, all of the file mode bits +specified in this volume of IEEE\ Std\ 1003.1-2001. +.LP +If \fBperm\fP is not specified, the \fB'='\fP operation shall make +no further modifications to the file mode bits. +.LP +If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP +for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation +mask of the invoking process, shall be set. +.LP +Otherwise, the file mode bits represented by the specified \fBwho\fP +and \fBperm\fP values shall be set. +.sp +.LP +When using the symbolic mode form on a regular file, it is implementation-defined +whether or not: +.IP " *" 3 +Requests to set the set-user-ID-on-execution or set-group-ID-on-execution +bit when all execute bits are currently clear and none +are being set are ignored. +.LP +.IP " *" 3 +Requests to clear all execute bits also clear the set-user-ID-on-execution +and set-group-ID-on-execution bits. +.LP +.IP " *" 3 +Requests to clear the set-user-ID-on-execution or set-group-ID-on-execution +bits when all execute bits are currently clear are +ignored. However, if the command \fIls\fP \fB-l\fP \fIfile\fP writes +an \fIs\fP in the +position indicating that the set-user-ID-on-execution or set-group-ID-on-execution +is set, the commands \fIchmod\fP \fBu-s\fP +\fIfile\fP or \fIchmod\fP \fBg-s\fP \fIfile\fP, respectively, shall +not be ignored. +.LP +.LP +When using the symbolic mode form on other file types, it is implementation-defined +whether or not requests to set or clear the +set-user-ID-on-execution or set-group-ID-on-execution bits are honored. +.LP +If the \fBwho\fP symbol \fBo\fP is used in conjunction with the \fBperm\fP +symbol \fBs\fP with no other \fBwho\fP symbols +being specified, the set-user-ID-on-execution and set-group-ID-on-execution +bits shall not be modified. It shall not be an error to +specify the \fBwho\fP symbol \fBo\fP in conjunction with the \fBperm\fP +symbol \fBs\fP. +.LP +The \fBperm\fP symbol \fBt\fP shall specify the S_ISVTX bit. When +used with a file of type directory, it can be used with the +\fBwho\fP symbol \fBa\fP, or with no \fBwho\fP symbol. It shall not +be an error to specify a \fBwho\fP symbol of \fBu\fP, +\fBg\fP, or \fBo\fP in conjunction with the \fBperm\fP symbol \fBt\fP, +but the meaning of these combinations is unspecified. +The effect when using the \fBperm\fP symbol \fBt\fP with any file +type other than directory is unspecified. +.LP +For an octal integer \fImode\fP operand, the file mode bits shall +be set absolutely. +.LP +For each bit set in the octal number, the corresponding file permission +bit shown in the following table shall be set; all other +file permission bits shall be cleared. For regular files, for each +bit set in the octal number corresponding to the +set-user-ID-on-execution or the set-group-ID-on-execution, bits shown +in the following table shall be set; if these bits are not +set in the octal number, they are cleared. For other file types, it +is implementation-defined whether or not requests to set or +clear the set-user-ID-on-execution or set-group-ID-on-execution bits +are honored. +.TS C +center; l1 l1 l1 l1 l1 l1 l1 l. +\fBOctal\fP \fBMode Bit\fP \fBOctal\fP \fBMode Bit\fP \fBOctal\fP \fBMode Bit\fP \fBOctal\fP \fBMode Bit\fP +\fB4000\fP S_ISUID \fB0400\fP S_IRUSR \fB0040\fP S_IRGRP \fB0004\fP S_IROTH +\fB2000\fP S_ISGID \fB0200\fP S_IWUSR \fB0020\fP S_IWGRP \fB0002\fP S_IWOTH +\fB1000\fP S_ISVTX \fB0100\fP S_IXUSR \fB0010\fP S_IXGRP \fB0001\fP S_IXOTH +.TE +.LP +When bits are set in the octal number other than those listed in the +table above, the behavior is unspecified. +.SS Grammar for chmod +.LP +The grammar and lexical conventions in this section describe the syntax +for the \fIsymbolic_mode\fP operand. The general +conventions for this style of grammar are described in \fIGrammar +Conventions\fP . A valid +\fIsymbolic_mode\fP can be represented as the non-terminal symbol +\fIsymbolic_mode\fP in the grammar. This formal syntax shall +take precedence over the preceding text syntax description. +.LP +The lexical processing is based entirely on single characters. Implementations +need not allow <blank>s within the single +argument being processed. +.sp +.RS +.nf + +\fB%start symbolic_mode +%% +.sp + +symbolic_mode : clause + | symbolic_mode ',' clause + ; +.sp + +clause : actionlist + | wholist actionlist + ; +.sp + +wholist : who + | wholist who + ; +.sp + +who : 'u' | 'g' | 'o' | 'a' + ; +.sp + +actionlist : action + | actionlist action + ; +.sp + +action : op + | op permlist + | op permcopy + ; +.sp + +permcopy : 'u' | 'g' | 'o' + ; +.sp + +op : '+' | '-' | '=' + ; +.sp + +permlist : perm + | perm permlist + ; +.sp + + +perm : 'r' | 'w' | 'x' | 'X' | 's' | 't' + ; +\fP +.fi +.RE +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The utility executed successfully and all requested changes were made. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Some implementations of the \fIchmod\fP utility change the mode of +a directory before the files in the directory when +performing a recursive ( \fB-R\fP option) change; others change the +directory mode after the files in the directory. If an +application tries to remove read or search permission for a file hierarchy, +the removal attempt fails if the directory is changed +first; on the other hand, trying to re-enable permissions to a restricted +hierarchy fails if directories are changed last. Users +should not try to make a hierarchy inaccessible to themselves. +.LP +Some implementations of \fIchmod\fP never used the process' \fIumask\fP +when changing +modes; systems conformant with this volume of IEEE\ Std\ 1003.1-2001 +do so when \fBwho\fP is not specified. Note the +difference between: +.sp +.RS +.nf + +\fBchmod a-w file +\fP +.fi +.RE +.LP +which removes all write permissions, and: +.sp +.RS +.nf + +\fBchmod -- -w file +\fP +.fi +.RE +.LP +which removes write permissions that would be allowed if \fBfile\fP +was created with the same \fIumask\fP. +.LP +Conforming applications should never assume that they know how the +set-user-ID and set-group-ID bits on directories are +interpreted. +.SH EXAMPLES +.TS C +center; l lw(40). +\fBMode\fP T{ +.na +\fBResults\fP +.ad +T} +\fIa\fP+= T{ +.na +Equivalent to \fIa\fP+, \fIa\fP=; clears all file mode bits. +.ad +T} +\fIgo\fP+-w T{ +.na +Equivalent to \fIgo\fP+, \fIgo\fP- \fIw\fP; clears group and other write bits. +.ad +T} +\fIg\fP=\fIo\fP-\fIw\fP T{ +.na +Equivalent to \fIg\fP= \fIo\fP, \fIg\fP- \fIw\fP; sets group bit to match other bits and then clears group write bit. +.ad +T} +\fIg\fP-\fIr\fP+\fIw\fP T{ +.na +Equivalent to \fIg\fP- \fIr\fP, \fIg\fP+ \fIw\fP; clears group read bit and sets group write bit. +.ad +T} +\fIuo\fP=\fIg\fP T{ +.na +Sets owner bits to match group bits and sets other bits to match group bits. +.ad +T} +.TE +.SH RATIONALE +.LP +The functionality of \fIchmod\fP is described substantially through +references to concepts defined in the System Interfaces +volume of IEEE\ Std\ 1003.1-2001. In this way, there is less duplication +of effort required for describing the interactions +of permissions. However, the behavior of this utility is not described +in terms of the \fIchmod\fP() function from the System Interfaces +volume of IEEE\ Std\ 1003.1-2001 because +that specification requires certain side effects upon alternate file +access control mechanisms that might not be appropriate, +depending on the implementation. +.LP +Implementations that support mandatory file and record locking as +specified by the 1984 /usr/group standard historically used +the combination of set-group-ID bit set and group execute bit clear +to indicate mandatory locking. This condition is usually set or +cleared with the symbolic mode \fBperm\fP symbol \fBl\fP instead of +the \fBperm\fP symbols \fBs\fP and \fBx\fP so that the +mandatory locking mode is not changed without explicit indication +that that was what the user intended. Therefore, the details on +how the implementation treats these conditions must be defined in +the documentation. This volume of IEEE\ Std\ 1003.1-2001 +does not require mandatory locking (nor does the System Interfaces +volume of IEEE\ Std\ 1003.1-2001), but does allow it as +an extension. However, this volume of IEEE\ Std\ 1003.1-2001 does +require that the \fIls\fP and \fIchmod\fP utilities work consistently +in this area. If \fIls\fP \fB-l\fP \fIfile\fP indicates that the set-group-ID +bit is set, \fIchmod\fP \fBg-s\fP +\fIfile\fP must clear it (assuming appropriate privileges exist to +change modes). +.LP +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. This +problem is avoided here by specifying only 0 and >0 as exit values. +.LP +The System Interfaces volume of IEEE\ Std\ 1003.1-2001 indicates that +implementation-defined restrictions may cause the +S_ISUID and S_ISGID bits to be ignored. This volume of IEEE\ Std\ 1003.1-2001 +allows the \fIchmod\fP utility to choose to +modify these bits before calling \fIchmod\fP() (or some function providing +equivalent +capabilities) for non-regular files. Among other things, this allows +implementations that use the set-user-ID and set-group-ID bits +on directories to enable extended features to handle these extensions +in an intelligent manner. +.LP +The \fBX\fP \fBperm\fP symbol was adopted from BSD-based systems because +it provides commonly desired functionality when doing +recursive ( \fB-R\fP option) modifications. Similar functionality +is not provided by the \fIfind\fP utility. Historical BSD versions +of \fIchmod\fP, however, only supported \fBX\fP with +\fIop\fP+; it has been extended in this volume of IEEE\ Std\ 1003.1-2001 +because it is also useful with \fIop\fP=. (It +has also been added for \fIop\fP- even though it duplicates \fBx\fP, +in this case, because it is intuitive and easier to +explain.) +.LP +The grammar was extended with the \fIpermcopy\fP non-terminal to allow +historical-practice forms of symbolic modes like +\fBo\fP= \fBu\fP \fB-g\fP (that is, set the "other" permissions to +the permissions of "owner" minus the permissions of +"group"). +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIls\fP, \fIumask\fP, the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, \fIchmod\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |