git.saurik.com Git - apple/file_cmds.git/blob

1 .\"-

4 .\"

5 .\" This code is derived from software contributed to Berkeley by

6 .\" the Institute of Electrical and Electronics Engineers, Inc.

7 .\"

8 .\" Redistribution and use in source and binary forms, with or without

9 .\" modification, are permitted provided that the following conditions

10 .\" are met:

11 .\" 1. Redistributions of source code must retain the above copyright

12 .\" notice, this list of conditions and the following disclaimer.

13 .\" 2. Redistributions in binary form must reproduce the above copyright

14 .\" notice, this list of conditions and the following disclaimer in the

15 .\" documentation and/or other materials provided with the distribution.

16 .\" 3. Neither the name of the University nor the names of its contributors

17 .\" may be used to endorse or promote products derived from this software

18 .\" without specific prior written permission.

19 .\"

20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

30 .\" SUCH DAMAGE.

31 .\"

32 .\" @(#)chmod.1 8.4 (Berkeley) 3/31/94

33 .\" $FreeBSD$

34 .\"

35 .Dd January 7, 2017

36 .Dt CHMOD 1

37 .Os

38 .Sh NAME

39 .Nm chmod

40 .Nd change file modes or Access Control Lists

41 .Sh SYNOPSIS

42 .Nm chmod

43 .Op Fl fv

44 .Op Fl R Op Fl H | L | P

45 .Ar mode

46 .Ar

47 .Nm chmod

48 .Op Fl fv

49 .Op Fl R Op Fl H | L | P

50 .Op -a | +a | =a

51 .Ar ACE

52 .Ar

53 .Nm chmod

54 .Op Fl fhv

55 .Op Fl R Op Fl H | L | P

56 .Op Fl E

57 .Ar

58 .Nm chmod

59 .Op Fl fhv

60 .Op Fl R Op Fl H | L | P

61 .Op Fl C

62 .Ar

63 .Nm chmod

64 .Op Fl fhv

65 .Op Fl R Op Fl H | L | P

66 .Op Fl N

67 .Ar

68 .Sh DESCRIPTION

69 The

70 .Nm chmod

71 utility modifies the file mode bits of the listed files

72 as specified by the

73 .Ar mode

74 operand. It may also be used to modify the Access Control

75 Lists (ACLs) associated with the listed files.

76 .Pp

77 The generic options are as follows:

78 .Bl -tag -width indent

79 .It Fl f

80 Do not display a diagnostic message if

81 .Nm chmod

82 could not modify the mode for

83 .Va file ,

84 nor modify the exit status to reflect such failures.

85 .It Fl H

86 If the

87 .Fl R

88 option is specified, symbolic links on the command line are followed

89 and hence unaffected by the command.

90 (Symbolic links encountered during tree traversal are not followed.)

91 .It Fl h

92 If the file is a symbolic link, change the mode of the link itself

93 rather than the file that the link points to.

94 .It Fl L

95 If the

96 .Fl R

97 option is specified, all symbolic links are followed.

98 .It Fl P

99 If the

100 .Fl R

101 option is specified, no symbolic links are followed.

102 This is the default.

103 .It Fl R

104 Change the modes of the file hierarchies rooted in the files,

105 instead of just the files themselves.

106 Beware of unintentionally matching the

107 .Dq Pa ".."

108 hard link to the parent directory when using wildcards like

109 .Dq Li ".*" .

110 .It Fl v

111 Cause

112 .Nm chmod

113 to be verbose, showing filenames as the mode is modified.

114 If the

115 .Fl v

116 flag is specified more than once, the old and new modes of the file

117 will also be printed, in both octal and symbolic notation.

118 .El

119 .Pp

120 The

121 .Fl H ,

122 .Fl L

123 and

124 .Fl P

125 options are ignored unless the

126 .Fl R

127 option is specified.

128 In addition, these options override each other and the

129 command's actions are determined by the last one specified.

130 .Pp

131 If

132 .Nm chmod

133 receives a

134 .Dv SIGINFO

135 signal (see the

136 .Cm status

137 argument for

138 .Xr stty 1 ) ,

139 then the current filename as well as the old and new modes are displayed.

140 .Pp

141 Only the owner of a file or the super-user is permitted to change

142 the mode of a file.

143 .Sh EXIT STATUS

144 .Ex -std

145 .Sh MODES

146 Modes may be absolute or symbolic.

147 An absolute mode is an octal number constructed from the sum of

148 one or more of the following values:

149 .Pp

150 .Bl -tag -width 6n -compact -offset indent

151 .It Li 4000

152 (the setuid bit).

153 Executable files with this bit set

154 will run with effective uid set to the uid of the file owner.

155 Directories with this bit set will force all files and

156 sub-directories created in them to be owned by the directory owner

157 and not by the uid of the creating process, if the underlying file

158 system supports this feature: see

159 .Xr chmod 2

160 and the

161 .Cm suiddir

162 option to

163 .Xr mount 8 .

164 .It Li 2000

165 (the setgid bit).

166 Executable files with this bit set

167 will run with effective gid set to the gid of the file owner.

168 .It Li 1000

169 (the sticky bit).

170 See

171 .Xr chmod 2

172 and

173 .Xr sticky 7 .

174 .It Li 0400

175 Allow read by owner.

176 .It Li 0200

177 Allow write by owner.

178 .It Li 0100

179 For files, allow execution by owner.

180 For directories, allow the owner to

181 search in the directory.

182 .It Li 0040

183 Allow read by group members.

184 .It Li 0020

185 Allow write by group members.

186 .It Li 0010

187 For files, allow execution by group members.

188 For directories, allow

189 group members to search in the directory.

190 .It Li 0004

191 Allow read by others.

192 .It Li 0002

193 Allow write by others.

194 .It Li 0001

195 For files, allow execution by others.

196 For directories allow others to

197 search in the directory.

198 .El

199 .Pp

200 For example, the absolute mode that permits read, write and execute by

201 the owner, read and execute by group members, read and execute by

202 others, and no set-uid or set-gid behaviour is 755

203 (400+200+100+040+010+004+001).

204 .Pp

205 The symbolic mode is described by the following grammar:

206 .Bd -literal -offset indent

207 mode ::= clause [, clause ...]

208 clause ::= [who ...] [action ...] action

209 action ::= op [perm ...]

210 who ::= a | u | g | o

211 op ::= + | \- | =

212 perm ::= r | s | t | w | x | X | u | g | o

213 .Ed

214 .Pp

215 The

216 .Ar who

217 symbols ``u'', ``g'', and ``o'' specify the user, group, and other parts

218 of the mode bits, respectively.

219 The

220 .Ar who

221 symbol ``a'' is equivalent to ``ugo''.

222 .Pp

223 The

224 .Ar perm

225 symbols represent the portions of the mode bits as follows:

226 .Pp

227 .Bl -tag -width Ds -compact -offset indent

228 .It r

229 The read bits.

230 .It s

231 The set-user-ID-on-execution and set-group-ID-on-execution bits.

232 .It t

233 The sticky bit.

234 .It w

235 The write bits.

236 .It x

237 The execute/search bits.

238 .It X

239 The execute/search bits if the file is a directory or any of the

240 execute/search bits are set in the original (unmodified) mode.

241 Operations with the

242 .Ar perm

243 symbol ``X'' are only meaningful in conjunction with the

244 .Ar op

245 symbol ``+'', and are ignored in all other cases.

246 .It u

247 The user permission bits in the original mode of the file.

248 .It g

249 The group permission bits in the original mode of the file.

250 .It o

251 The other permission bits in the original mode of the file.

252 .El

253 .Pp

254 The

255 .Ar op

256 symbols represent the operation performed, as follows:

257 .Bl -tag -width 4n

258 .It +

259 If no value is supplied for

260 .Ar perm ,

261 the ``+'' operation has no effect.

262 If no value is supplied for

263 .Ar who ,

264 each permission bit specified in

265 .Ar perm ,

266 for which the corresponding bit in the file mode creation mask

267 (see

268 .Xr umask 2 )

269 is clear, is set.

270 Otherwise, the mode bits represented by the specified

271 .Ar who

272 and

273 .Ar perm

274 values are set.

275 .It \&\-

276 If no value is supplied for

277 .Ar perm ,

278 the ``\-'' operation has no effect.

279 If no value is supplied for

280 .Ar who ,

281 each permission bit specified in

282 .Ar perm ,

283 for which the corresponding bit in the file mode creation mask

284 is set, is cleared.

285 Otherwise, the mode bits represented by the specified

286 .Ar who

287 and

288 .Ar perm

289 values are cleared.

290 .It =

291 The mode bits specified by the

292 .Ar who

293 value are cleared, or, if no

294 .Ar who

295 value is specified, the owner, group

296 and other mode bits are cleared.

297 Then, if no value is supplied for

298 .Ar who ,

299 each permission bit specified in

300 .Ar perm ,

301 for which the corresponding bit in the file mode creation mask

302 is clear, is set.

303 Otherwise, the mode bits represented by the specified

304 .Ar who

305 and

306 .Ar perm

307 values are set.

308 .El

309 .Pp

310 Each

311 .Ar clause

312 specifies one or more operations to be performed on the mode

313 bits, and each operation is applied to the mode bits in the

314 order specified.

315 .Pp

316 Operations upon the other permissions only (specified by the symbol

317 ``o'' by itself), in combination with the

318 .Ar perm

319 symbols ``s'' or ``t'', are ignored.

320 .Pp

321 The ``w'' permission on directories will permit file creation, relocation,

322 and copy into that directory.

323 Files created within the directory itself will inherit its group ID.

324 .Sh EXAMPLES OF VALID MODES

325 .Bl -tag -width "u=rwx,go=u-w" -compact

326 .It Li 644

327 make a file readable by anyone and writable by the owner only.

328 .Pp

329 .It Li go-w

330 deny write permission to group and others.

331 .Pp

332 .It Li =rw,+X

333 set the read and write permissions to the usual defaults, but

334 retain any execute permissions that are currently set.

335 .Pp

336 .It Li +X

337 make a directory or file searchable/executable by everyone if it is

338 already searchable/executable by anyone.

339 .Pp

340 .It Li 755

341 .It Li u=rwx,go=rx

342 .It Li u=rwx,go=u-w

343 make a file readable/executable by everyone and writable by the owner only.

344 .Pp

345 .It Li go=

346 clear all mode bits for group and others.

347 .Pp

348 .It Li g=u-w

349 set the group bits equal to the user bits, but clear the group write bit.

350 .El

351 .Sh ACL MANIPULATION OPTIONS

352 ACLs are manipulated using extensions to the symbolic mode

353 grammar. Each file has one ACL, containing an ordered list of entries.

354 Each entry refers to a user or group, and grants or denies a set of

355 permissions.

356 In cases where a user and a group exist with the same name, the

357 user/group name can be prefixed with "user:" or "group:" in order to

358 specify the type of name.

359 .Pp

360 If the user or group name contains spaces you can use ':' as the delimiter

361 between name and permission.

362 .Pp

363 The following permissions are applicable to all filesystem objects:

364 .Bl -tag -width 6n -compact -offset indent

365 .It delete

366 Delete the item. Deletion may be granted by either this permission

367 on an object or the delete_child right on the containing directory.

368 .It readattr

369 Read an object's basic attributes. This is implicitly granted if

370 the object can be looked up and not explicitly denied.

371 .It writeattr

372 Write an object's basic attributes.

373 .It readextattr

374 Read extended attributes.

375 .It writeextattr

376 Write extended attributes.

377 .It readsecurity

378 Read an object's extended security information (ACL).

379 .It writesecurity

380 Write an object's security information (ownership, mode, ACL).

381 .It chown

382 Change an object's ownership.

383 .El

384 .Pp

385 The following permissions are applicable to directories:

386 .Bl -tag -width 6n -compact -offset indent

387 .It list

388 List entries.

389 .It search

390 Look up files by name.

391 .It add_file

392 Add a file.

393 .It add_subdirectory

394 Add a subdirectory.

395 .It delete_child

396 Delete a contained object. See the file delete permission above.

397 .El

398 .Pp

399 The following permissions are applicable to non-directory filesystem objects:

400 .Bl -tag -width 6n -compact -offset indent

401 .It read

402 Open for reading.

403 .It write

404 Open for writing.

405 .It append

406 Open for writing, but in a fashion that only allows writes into areas of

407 the file not previously written.

408 .It execute

409 Execute the file as a script or program.

410 .El

411 .Pp

412 ACL inheritance is controlled with the following permissions words, which

413 may only be applied to directories:

414 .Bl -tag -width 6n -compact -offset indent

415 .It file_inherit

416 Inherit to files.

417 .It directory_inherit

418 Inherit to directories.

419 .It limit_inherit

420 This flag is only relevant to entries inherited by subdirectories; it

421 causes the directory_inherit flag to be cleared in the entry that is

422 inherited, preventing further nested subdirectories from also

423 inheriting the entry.

424 .It only_inherit

425 The entry is inherited by created items but not considered when processing

426 the ACL.

427 .El

428 .Pp

429 The ACL manipulation options are as follows:

430 .Bl -tag -width Ds

431 .It \fB+a\fR

432 The +a mode parses a new ACL entry from the next argument on

433 the commandline and inserts it into the canonical location in the

434 ACL. If the supplied entry refers to an identity already listed, the

435 two entries are combined.

436 .Pp

437 \fBExamples\fR

438 # ls -le

439 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

440 # chmod +a "admin allow write" file1

441 # ls -le

442 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

443 owner: juser

444 1: admin allow write

445 # chmod +a "guest deny read" file1

446 # ls -le

447 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

448 owner: juser

449 1: guest deny read

450 2: admin allow write

451 # chmod +a "admin allow delete" file1

452 # ls -le

453 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

454 owner: juser

455 1: guest deny read

456 2: admin allow write,delete

457 # chmod +a "User 1:allow:read" file

458 # ls -le

459 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

460 owner: juser

461 1: guest deny read

462 2: User 1 allow read

463 3: admin allow write,delete

464 .Pp

465 The +a mode strives to maintain correct canonical form for the ACL.

466 local deny

467 local allow

468 inherited deny

469 inherited allow

470 .Pp

471 By default, chmod adds entries to the top of the local deny and local

472 allow lists. Inherited entries are added by using the +ai mode.

473 .Pp

474 \fBExamples\fR

475 # ls -le

476 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

477 owner: juser

478 1: guest deny read

479 2: admin allow write,delete

480 3: juser inherited deny delete

481 4: admin inherited allow delete

482 5: backup inherited deny read

483 6: admin inherited allow write-security

484 # chmod +ai "others allow read" file1

485 # ls -le

486 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

487 owner: juser

488 1: guest deny read

489 2: admin allow write,delete

490 3: juser inherited deny delete

491 4: others inherited allow read

492 5: admin inherited allow delete

493 6: backup inherited deny read

494 7: admin inherited allow write-security

495 .It \fB+a#\fR

496 When a specific ordering is required, the exact location at which an

497 entry will be inserted is specified with the +a# mode.

498 .Pp

499 \fBExamples\fR

500 # ls -le

501 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

502 owner: juser

503 1: guest deny read

504 2: admin allow write

505 # chmod +a# 2 "others deny read" file1

506 # ls -le

507 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

508 owner: juser

509 1: guest deny read

510 2: others deny read

511 3: admin allow write

512 .Pp

513 The +ai# mode may be used to insert inherited entries at a specific

514 location. Note that these modes allow non-canonical ACL ordering to

515 be constructed.

516 .It Fl a

517 The -a mode is used to delete ACL entries. All entries exactly

518 matching the supplied entry will be deleted. If the entry lists a

519 subset of rights granted by an entry, only the rights listed are

520 removed. Entries may also be deleted by index using the -a# mode.

521 .Pp

522 \fBExamples\fR

523 # ls -le

524 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

525 owner: juser

526 1: guest deny read

527 2: admin allow write,delete

528 # chmod -a# 1 file1

529 # ls -le

530 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

531 owner: juser

532 1: admin allow write,delete

533 # chmod -a "admin allow write" file1

534 # ls -le

535 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

536 owner: juser

537 1: admin allow delete

538 .Pp

539 Inheritance is not considered when processing the -a mode; rights and

540 entries will be removed regardless of their inherited state.

541 .Pp

542 If the user or group name contains spaces you can use ':' as the delimiter

543 .Pp

544 \fBExample\fR

545 # chmod +a "User 1:allow:read" file

546 .It \fB=a#\fR

547 Individual entries are rewritten using the =a# mode.

548 .Pp

549 \fBExamples\fR

550 # ls -le

551 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

552 owner: juser

553 1: admin allow delete

554 # chmod =a# 1 "admin allow write,chown"

555 # ls -le

556 -rw-r--r--+ 1 juser wheel 0 Apr 28 14:06 file1

557 owner: juser

558 1: admin allow write,chown

559 .Pp

560 This mode may not be used to add new entries.

561 .It Fl E

562 Reads the ACL information from stdin, as a sequential list

563 of ACEs, separated by newlines. If the information parses correctly,

564 the existing information is replaced.

565 .It Fl C

566 Returns false if any of the named files have ACLs in non-canonical order.

567 .It Fl i

568 Removes the 'inherited' bit from all entries in the named file(s) ACLs.

569 .It Fl I

570 Removes all inherited entries from the named file(s) ACL(s).

571 .It Fl N

572 Removes the ACL from the named file(s).

573 .El

574 .Sh COMPATIBILITY

575 The

576 .Fl v

577 option is non-standard and its use in scripts is not recommended.

578 .Sh SEE ALSO

579 .Xr chflags 1 ,

580 .Xr install 1 ,

581 .Xr chmod 2 ,

582 .Xr stat 2 ,

583 .Xr umask 2 ,

584 .Xr fts 3 ,

585 .Xr setmode 3 ,

586 .Xr sticky 7 ,

587 .Xr symlink 7 ,

588 .Xr chown 8 ,

589 .Xr mount 8

590 .Sh STANDARDS

591 The

592 .Nm chmod

593 utility is expected to be

594 .St -p1003.2

595 compatible with the exception of the

596 .Ar perm

597 symbol

598 .Dq t

599 which is not included in that standard.

600 .Sh HISTORY

601 A

602 .Nm chmod

603 command appeared in

604 .At v1 .