logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

chmod.1p (17647B)


  1. '\" et
  2. .TH CHMOD "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. chmod
  12. \(em change the file modes
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. chmod \fB[\fR-R\fB] \fImode file\fR...
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR chmod
  21. utility shall change any or all of the file mode bits of the file named
  22. by each
  23. .IR file
  24. operand in the way specified by the
  25. .IR mode
  26. operand.
  27. .P
  28. It is implementation-defined whether and how the
  29. .IR chmod
  30. utility affects any alternate or additional file access control
  31. mechanism (see the Base Definitions volume of POSIX.1\(hy2017,
  32. .IR "Section 4.5" ", " "File Access Permissions")
  33. being used for the specified file.
  34. .P
  35. Only a process whose effective user ID matches the user ID of the file,
  36. or a process with appropriate privileges, shall be permitted to
  37. change the file mode bits of a file.
  38. .P
  39. Upon successfully changing the file mode bits of a file, the
  40. .IR chmod
  41. utility shall mark for update the last file status change timestamp
  42. of the file.
  43. .SH OPTIONS
  44. The
  45. .IR chmod
  46. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  47. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  48. .P
  49. The following option shall be supported:
  50. .IP "\fB\-R\fP" 10
  51. Recursively change file mode bits. For each
  52. .IR file
  53. operand that names a directory,
  54. .IR chmod
  55. shall change the file mode bits of the directory and all files in the
  56. file hierarchy below it.
  57. .SH OPERANDS
  58. The following operands shall be supported:
  59. .IP "\fImode\fR" 10
  60. Represents the change to be made to the file mode bits of each
  61. file named by one of the
  62. .IR file
  63. operands; see the EXTENDED DESCRIPTION section.
  64. .IP "\fIfile\fR" 10
  65. A pathname of a file whose file mode bits shall be modified.
  66. .SH STDIN
  67. Not used.
  68. .SH "INPUT FILES"
  69. None.
  70. .SH "ENVIRONMENT VARIABLES"
  71. The following environment variables shall affect the execution of
  72. .IR chmod :
  73. .IP "\fILANG\fP" 10
  74. Provide a default value for the internationalization variables that are
  75. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  76. .IR "Section 8.2" ", " "Internationalization Variables"
  77. for the precedence of internationalization variables used to determine
  78. the values of locale categories.)
  79. .IP "\fILC_ALL\fP" 10
  80. If set to a non-empty string value, override the values of all the
  81. other internationalization variables.
  82. .IP "\fILC_CTYPE\fP" 10
  83. Determine the locale for the interpretation of sequences of bytes of
  84. text data as characters (for example, single-byte as opposed to
  85. multi-byte characters in arguments).
  86. .IP "\fILC_MESSAGES\fP" 10
  87. .br
  88. Determine the locale that should be used to affect the format and
  89. contents of diagnostic messages written to standard error.
  90. .IP "\fINLSPATH\fP" 10
  91. Determine the location of message catalogs for the processing of
  92. .IR LC_MESSAGES .
  93. .SH "ASYNCHRONOUS EVENTS"
  94. Default.
  95. .SH STDOUT
  96. Not used.
  97. .SH STDERR
  98. The standard error shall be used only for diagnostic messages.
  99. .SH "OUTPUT FILES"
  100. None.
  101. .SH "EXTENDED DESCRIPTION"
  102. The
  103. .IR mode
  104. operand shall be either a
  105. .IR symbolic_mode
  106. expression or a non-negative octal integer. The
  107. .IR symbolic_mode
  108. form is described by the grammar later in this section.
  109. .P
  110. Each
  111. .BR clause
  112. shall specify an operation to be performed on the current file mode
  113. bits of each
  114. .IR file .
  115. The operations shall be performed on each
  116. .IR file
  117. in the order in which the
  118. .BR clause s
  119. are specified.
  120. .P
  121. The
  122. .BR who
  123. symbols
  124. .BR u ,
  125. .BR g ,
  126. and
  127. .BR o
  128. shall specify the
  129. .IR user ,
  130. .IR group ,
  131. and
  132. .IR other
  133. parts of the file mode bits, respectively. A
  134. .BR who
  135. consisting of the symbol
  136. .BR a
  137. shall be equivalent to
  138. .BR ugo .
  139. .P
  140. The
  141. .BR perm
  142. symbols
  143. .BR r ,
  144. .BR w ,
  145. and
  146. .BR x
  147. represent the
  148. .IR read ,
  149. .IR write ,
  150. and
  151. .IR execute /\c
  152. .IR search
  153. portions of file mode bits, respectively. The
  154. .BR perm
  155. symbol
  156. .BR s
  157. shall represent the
  158. .IR "set-user-ID-on-execution"
  159. (when
  160. .BR who
  161. contains or implies
  162. .BR u )
  163. and
  164. .IR "set-group-ID-on-execution"
  165. (when
  166. .BR who
  167. contains or implies
  168. .BR g )
  169. bits.
  170. .P
  171. The
  172. .BR perm
  173. symbol
  174. .BR X
  175. shall represent the execute/search portion of the file mode bits if the
  176. file is a directory or if the current (unmodified) file mode bits have
  177. at least one of the execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It
  178. shall be ignored if the file is not a directory and none of the execute
  179. bits are set in the current file mode bits.
  180. .P
  181. The
  182. .BR permcopy
  183. symbols
  184. .BR u ,
  185. .BR g ,
  186. and
  187. .BR o
  188. shall represent the current permissions associated with the user,
  189. group, and other parts of the file mode bits, respectively. For the
  190. remainder of this section,
  191. .BR perm
  192. refers to the non-terminals
  193. .BR perm
  194. and
  195. .BR permcopy
  196. in the grammar.
  197. .P
  198. If multiple
  199. .BR actionlist s
  200. are grouped with a single
  201. .BR wholist
  202. in the grammar, each
  203. .BR actionlist
  204. shall be applied in the order specified with that
  205. .BR wholist .
  206. The
  207. .IR op
  208. symbols shall represent the operation performed, as follows:
  209. .IP "\fR+\fP" 6
  210. If
  211. .BR perm
  212. is not specified, the
  213. .BR '\(pl'
  214. operation shall not change the file mode bits.
  215. .RS 6
  216. .P
  217. If
  218. .BR who
  219. is not specified, the file mode bits represented by
  220. .BR perm
  221. for the owner, group, and other permissions, except for those with
  222. corresponding bits in the file mode creation mask of the invoking
  223. process, shall be set.
  224. .P
  225. Otherwise, the file mode bits represented by the specified
  226. .BR who
  227. and
  228. .BR perm
  229. values shall be set.
  230. .RE
  231. .IP "\fR\-\fP" 6
  232. If
  233. .BR perm
  234. is not specified, the
  235. .BR '\-'
  236. operation shall not change the file mode bits.
  237. .RS 6
  238. .P
  239. If
  240. .BR who
  241. is not specified, the file mode bits represented by
  242. .BR perm
  243. for the owner, group, and other permissions, except for those with
  244. corresponding bits in the file mode creation mask of the invoking
  245. process, shall be cleared.
  246. .P
  247. Otherwise, the file mode bits represented by the specified
  248. .BR who
  249. and
  250. .BR perm
  251. values shall be cleared.
  252. .RE
  253. .IP "\fR=\fP" 6
  254. Clear the file mode bits specified by the
  255. .BR who
  256. value, or, if no
  257. .BR who
  258. value is specified, all of the file mode bits specified in this volume of POSIX.1\(hy2017.
  259. .RS 6
  260. .P
  261. If
  262. .BR perm
  263. is not specified, the
  264. .BR '='
  265. operation shall make no further modifications to the file mode bits.
  266. .P
  267. If
  268. .BR who
  269. is not specified, the file mode bits represented by
  270. .BR perm
  271. for the owner, group, and other permissions, except for those with
  272. corresponding bits in the file mode creation mask of the invoking
  273. process, shall be set.
  274. .P
  275. Otherwise, the file mode bits represented by the specified
  276. .BR who
  277. and
  278. .BR perm
  279. values shall be set.
  280. .RE
  281. .P
  282. When using the symbolic mode form on a regular file, it is
  283. implementation-defined whether or not:
  284. .IP " *" 4
  285. Requests to set the set-user-ID-on-execution or
  286. set-group-ID-on-execution bit when all execute bits are currently clear
  287. and none are being set are ignored.
  288. .IP " *" 4
  289. Requests to clear all execute bits also clear the
  290. set-user-ID-on-execution and set-group-ID-on-execution bits.
  291. .IP " *" 4
  292. Requests to clear the set-user-ID-on-execution or
  293. set-group-ID-on-execution bits when all execute bits are currently
  294. clear are ignored. However, if the command
  295. .IR ls
  296. .BR \-l
  297. .IR file
  298. writes an
  299. .IR s
  300. in the position indicating that the set-user-ID-on-execution or
  301. set-group-ID-on-execution is set, the commands
  302. .IR chmod
  303. .BR u\-s
  304. .IR file
  305. or
  306. .IR chmod
  307. .BR g\-s
  308. .IR file ,
  309. respectively, shall not be ignored.
  310. .P
  311. When using the symbolic mode form on other file types, it is
  312. implementation-defined whether or not requests to set or clear the
  313. set-user-ID-on-execution or set-group-ID-on-execution bits are
  314. honored.
  315. .P
  316. If the
  317. .BR who
  318. symbol
  319. .BR o
  320. is used in conjunction with the
  321. .BR perm
  322. symbol
  323. .BR s
  324. with no other
  325. .BR who
  326. symbols being specified, the set-user-ID-on-execution and
  327. set-group-ID-on-execution bits shall not be modified. It shall not be
  328. an error to specify the
  329. .BR who
  330. symbol
  331. .BR o
  332. in conjunction with the
  333. .BR perm
  334. symbol
  335. .BR s .
  336. .P
  337. The
  338. .BR perm
  339. symbol
  340. .BR t
  341. shall specify the S_ISVTX bit. When used with a file of type
  342. directory, it can be used with the
  343. .BR who
  344. symbol
  345. .BR a ,
  346. or with no
  347. .BR who
  348. symbol. It shall not be an error to specify a
  349. .BR who
  350. symbol of
  351. .BR u ,
  352. .BR g ,
  353. or
  354. .BR o
  355. in conjunction with the
  356. .BR perm
  357. symbol
  358. .BR t ,
  359. but the meaning of these combinations is unspecified. The effect when
  360. using the
  361. .BR perm
  362. symbol
  363. .BR t
  364. with any file type other than directory is unspecified.
  365. .P
  366. For an octal integer
  367. .IR mode
  368. operand, the file mode bits shall be set absolutely.
  369. .P
  370. For each bit set in the octal number, the corresponding file permission
  371. bit shown in the following table shall be set; all other file
  372. permission bits shall be cleared. For regular files, for each bit set
  373. in the octal number corresponding to the set-user-ID-on-execution or
  374. the set-group-ID-on-execution, bits shown in the following table shall
  375. be set; if these bits are not set in the octal number, they are
  376. cleared. For other file types, it is implementation-defined whether
  377. or not requests to set or clear the set-user-ID-on-execution or
  378. set-group-ID-on-execution bits are honored.
  379. .TS
  380. center tab(@) box;
  381. cB cB | cB cB | cB cB | cB cB
  382. nB l | nB l | nB l | nB l.
  383. Octal@Mode Bit@Octal@Mode Bit@Octal@Mode Bit@Octal@Mode Bit
  384. _
  385. 4000@S_ISUID@0400@S_IRUSR@0040@S_IRGRP@0004@S_IROTH
  386. _
  387. 2000@S_ISGID@0200@S_IWUSR@0020@S_IWGRP@0002@S_IWOTH
  388. _
  389. 1000@S_ISVTX@0100@S_IXUSR@0010@S_IXGRP@0001@S_IXOTH
  390. .TE
  391. .P
  392. When bits are set in the octal number other than those listed in the
  393. table above, the behavior is unspecified.
  394. .SS "Grammar for chmod"
  395. .P
  396. The grammar and lexical conventions in this section describe the syntax
  397. for the
  398. .IR symbolic_mode
  399. operand. The general conventions for this style of grammar are
  400. described in
  401. .IR "Section 1.3" ", " "Grammar Conventions".
  402. A valid
  403. .IR symbolic_mode
  404. can be represented as the non-terminal symbol
  405. .IR symbolic_mode
  406. in the grammar. This formal syntax shall take precedence over the
  407. preceding text syntax description.
  408. .P
  409. The lexical processing is based entirely on single characters.
  410. Implementations need not allow
  411. <blank>
  412. characters within the single argument being processed.
  413. .sp
  414. .RS 4
  415. .nf
  416. %start symbolic_mode
  417. %%
  418. .P
  419. symbolic_mode : clause
  420. | symbolic_mode \(aq,\(aq clause
  421. ;
  422. .P
  423. clause : actionlist
  424. | wholist actionlist
  425. ;
  426. .P
  427. wholist : who
  428. | wholist who
  429. ;
  430. .P
  431. who : \(aqu\(aq | \(aqg\(aq | \(aqo\(aq | \(aqa\(aq
  432. ;
  433. .P
  434. actionlist : action
  435. | actionlist action
  436. ;
  437. .P
  438. action : op
  439. | op permlist
  440. | op permcopy
  441. ;
  442. .P
  443. permcopy : \(aqu\(aq | \(aqg\(aq | \(aqo\(aq
  444. ;
  445. .P
  446. op : \(aq+\(aq | \(aq-\(aq | \(aq=\(aq
  447. ;
  448. .P
  449. permlist : perm
  450. | perm permlist
  451. ;
  452. .P
  453. perm : \(aqr\(aq | \(aqw\(aq | \(aqx\(aq | \(aqX\(aq | \(aqs\(aq | \(aqt\(aq
  454. ;
  455. .fi
  456. .P
  457. .RE
  458. .SH "EXIT STATUS"
  459. The following exit values shall be returned:
  460. .IP "\00" 6
  461. The utility executed successfully and all requested changes were made.
  462. .IP >0 6
  463. An error occurred.
  464. .SH "CONSEQUENCES OF ERRORS"
  465. Default.
  466. .LP
  467. .IR "The following sections are informative."
  468. .SH "APPLICATION USAGE"
  469. Some implementations of the
  470. .IR chmod
  471. utility change the mode of a directory before the files in the
  472. directory when performing a recursive (\c
  473. .BR \-R
  474. option) change; others change the directory mode after the files in the
  475. directory. If an application tries to remove read or search permission
  476. for a file hierarchy, the removal attempt fails if the directory is
  477. changed first; on the other hand, trying to re-enable permissions to a
  478. restricted hierarchy fails if directories are changed last. Users
  479. should not try to make a hierarchy inaccessible to themselves.
  480. .P
  481. Some implementations of
  482. .IR chmod
  483. never used the
  484. .IR umask
  485. of the process when changing modes; systems conformant with this volume of POSIX.1\(hy2017
  486. do so when
  487. .BR who
  488. is not specified. Note the difference between:
  489. .sp
  490. .RS 4
  491. .nf
  492. chmod a-w file
  493. .fi
  494. .P
  495. .RE
  496. .P
  497. which removes all write permissions, and:
  498. .sp
  499. .RS 4
  500. .nf
  501. chmod -- -w file
  502. .fi
  503. .P
  504. .RE
  505. .P
  506. which removes write permissions that would be allowed if
  507. .BR file
  508. was created with the same
  509. .IR umask .
  510. .P
  511. Conforming applications should never assume that they know how the
  512. set-user-ID and set-group-ID bits on directories are interpreted.
  513. .SH EXAMPLES
  514. .ad l
  515. .TS
  516. center tab(@) box;
  517. cB | cB
  518. l | lw(3i).
  519. Mode@Results
  520. _
  521. \fIa\fP+=@T{
  522. Equivalent to
  523. .IR a +,\c
  524. .IR a =;
  525. clears all file mode bits.
  526. T}
  527. \fIgo\fP+\-w@T{
  528. Equivalent to
  529. .IR go +,\c
  530. .IR go \-\c
  531. .IR w ;
  532. clears group and other write bits.
  533. T}
  534. \fIg\fR=\fIo\fR\-\fIw\fR@T{
  535. Equivalent to
  536. .IR g =\c
  537. .IR o ,\c
  538. .IR g \-\c
  539. .IR w ;
  540. sets group bit to match other bits and then clears group write bit.
  541. T}
  542. \fIg\fR\-\fIr\fR+\fIw\fR@T{
  543. Equivalent to
  544. .IR g \-\c
  545. .IR r ,\c
  546. .IR g +\c
  547. .IR w ;
  548. clears group read bit and sets group write bit.
  549. T}
  550. \fIuo\fR=\fIg\fR@T{
  551. Sets owner bits to match group bits and sets other bits to
  552. match group bits.
  553. T}
  554. .TE
  555. .ad b
  556. .SH RATIONALE
  557. The functionality of
  558. .IR chmod
  559. is described substantially through references to concepts defined in
  560. the System Interfaces volume of POSIX.1\(hy2017. In this way, there is less duplication of effort required
  561. for describing the interactions of permissions. However, the behavior
  562. of this utility is not described in terms of the
  563. \fIchmod\fR()
  564. function from the System Interfaces volume of POSIX.1\(hy2017 because that specification requires certain
  565. side-effects upon alternate file access control mechanisms that might
  566. not be appropriate, depending on the implementation.
  567. .P
  568. Implementations that support mandatory file and record locking as
  569. specified
  570. by the 1984 /usr/group standard historically used the combination of set-group-ID bit set
  571. and group execute bit clear to indicate mandatory locking. This
  572. condition is usually set or cleared with the symbolic mode
  573. .BR perm
  574. symbol
  575. .BR l
  576. instead of the
  577. .BR perm
  578. symbols
  579. .BR s
  580. and
  581. .BR x
  582. so that the mandatory locking mode is not changed without explicit
  583. indication that that was what the user intended. Therefore, the details
  584. on how the implementation treats these conditions must be defined in
  585. the documentation. This volume of POSIX.1\(hy2017 does not require mandatory locking (nor does
  586. the System Interfaces volume of POSIX.1\(hy2017), but does allow it as an extension. However, this volume of POSIX.1\(hy2017 does
  587. require that the
  588. .IR ls
  589. and
  590. .IR chmod
  591. utilities work consistently in this area. If
  592. .IR ls
  593. .BR \-l
  594. .IR file
  595. indicates that the set-group-ID bit is set,
  596. .IR chmod
  597. .BR g\-s
  598. .IR file
  599. must clear it (assuming appropriate privileges exist to change modes).
  600. .P
  601. The System V and BSD versions use different exit status codes. Some
  602. implementations used the exit status as a count of the number of errors
  603. that occurred; this practice is unworkable since it can overflow the
  604. range of valid exit status values. This problem is avoided here by
  605. specifying only 0 and >0 as exit values.
  606. .P
  607. The System Interfaces volume of POSIX.1\(hy2017 indicates that implementation-defined restrictions may cause
  608. the S_ISUID and S_ISGID bits to be ignored. This volume of POSIX.1\(hy2017 allows the
  609. .IR chmod
  610. utility to choose to modify these bits before calling
  611. \fIchmod\fR()
  612. (or some function providing equivalent capabilities) for non-regular
  613. files. Among other things, this allows implementations that use the
  614. set-user-ID and set-group-ID bits on directories to enable extended
  615. features to
  616. handle these extensions in an intelligent manner.
  617. .P
  618. The
  619. .BR X
  620. .BR perm
  621. symbol was adopted from BSD-based systems because it provides commonly
  622. desired functionality when doing recursive (\c
  623. .BR \-R
  624. option) modifications. Similar functionality is not provided by the
  625. .IR find
  626. utility. Historical BSD versions of
  627. .IR chmod ,
  628. however, only supported
  629. .BR X
  630. with
  631. .IR op +;
  632. it has been extended in this volume of POSIX.1\(hy2017 because it is also useful with
  633. .IR op =.
  634. (It has also been added for
  635. .IR op \-
  636. even though it duplicates
  637. .BR x ,
  638. in this case, because it is intuitive and easier to explain.)
  639. .P
  640. The grammar was extended with the
  641. .IR permcopy
  642. non-terminal to allow historical-practice forms of symbolic modes like
  643. .BR o =\c
  644. .BR u
  645. .BR \-g
  646. (that is, set the ``other'' permissions to the permissions of ``owner''
  647. minus the permissions of ``group'').
  648. .SH "FUTURE DIRECTIONS"
  649. None.
  650. .SH "SEE ALSO"
  651. .IR "\fIls\fR\^",
  652. .IR "\fIumask\fR\^"
  653. .P
  654. The Base Definitions volume of POSIX.1\(hy2017,
  655. .IR "Section 4.5" ", " "File Access Permissions",
  656. .IR "Chapter 8" ", " "Environment Variables",
  657. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  658. .P
  659. The System Interfaces volume of POSIX.1\(hy2017,
  660. .IR "\fIchmod\fR\^(\|)"
  661. .\"
  662. .SH COPYRIGHT
  663. Portions of this text are reprinted and reproduced in electronic form
  664. from IEEE Std 1003.1-2017, Standard for Information Technology
  665. -- Portable Operating System Interface (POSIX), The Open Group Base
  666. Specifications Issue 7, 2018 Edition,
  667. Copyright (C) 2018 by the Institute of
  668. Electrical and Electronics Engineers, Inc and The Open Group.
  669. In the event of any discrepancy between this version and the original IEEE and
  670. The Open Group Standard, the original IEEE and The Open Group Standard
  671. is the referee document. The original Standard can be obtained online at
  672. http://www.opengroup.org/unix/online.html .
  673. .PP
  674. Any typographical or formatting errors that appear
  675. in this page are most likely
  676. to have been introduced during the conversion of the source files to
  677. man page format. To report such errors, see
  678. https://www.kernel.org/doc/man-pages/reporting_bugs.html .