chmod

chmod

Original author(s)	AT&T Bell Laboratories
Developer(s)	Various open-source and commercial developers
Initial release	3 November 1971 (1971-11-03)
Written in	Plan 9: C
Operating system	Unix, Unix-like, Plan 9, Inferno, IBM i
Platform	Cross-platform
Type	Command
License	coreutils: GPLv3 Plan 9: MIT License

chmod is a shell command for changing access permissions and special mode flags of files (including special files such as directories). The name is short for change mode where mode refers to the permissions and flags collectively.

The command originated in AT&T Unix version 1 and was exclusive to Unix and Unix-like operating systems until it was ported to other operating systems such as Windows (in UnxUtils) and IBM i.

In Unix and Unix-like operating systems, a system call with the same name as the command, chmod(), provides access to the underlying access control data. The command exposes the capabilities of the system call to a shell user.

As the need for enhanced file-system permissions grew, access-control lists were added to many file systems to augment the modes controlled via chmod.

The implementation of chmod bundled in GNU coreutils was written by David MacKenzie and Jim Meyering.

Use

Although the syntax of the command varies somewhat by implementation, it generally accepts either a single octal value to which to set the permission value or a comma-delimited list of symbolic specifiers that describe how to change the current settings. A command ends with a space-delimited list of paths to files to be modified.

Changing permissions is only allowed for the superuser (root) and the owner of a file.

If a symbolic link is specified, the linked file is affected. Permissions directly associated with a symbolic link file system entry are typically not used.

Options

Optional, command-line options may include:

• -R recursive; include contained files and subdirectories of specified directories
• -v verbose; log changed file names

Permission notation

To view the permission settings of a file, the ls or stat commands may be used.

ls -l logs permissions in a symbolic notation that consists of 10 letters. The first indicates the type of the file system entry, such as dash for regular file and 'd' for directory. Following that are three sets of three letters that indicate read, write and execute permissions grouped by user (ower), group and others. Each position is either dash to indicate lack of permission or the single-letter abbreviation for the permission to indicate that its granted. For example:

$ ls -l findPhoneNumbers.sh
-rwxr-xr--  1 dgerman  staff  823 Dec 16 15:03 findPhoneNumbers.sh

The permission specifier -rwxr-xr-- starts with a dash which indicates that findPhoneNumbers.sh is a file; not a directory. The next three letters rwx indicate that the file can be read, written, and executed by the owning user dgerman. The next three letters r-x indicate that the file can be read and executed by members of the staff group. And the last three letters r-- indicate that the file is read-only for other users.

stat -c %a logs permissions in numeric notation. For example:

$ stat -c %a findPhoneNumbers.sh
754

Octal notation

The chmod octal format is up to four digits. The last three define permissions for the owning user, owning group, and others. An optional leading 4th digit specifies the special setuid, setgid, and sticky flags. Each of the last three digits represents a bit-field which controls the read (4), write (2) and execute (1) permissions, respectively. A set bit (1) grants the action, while a clear bit (0) denies it.

Octal digit permission

#	bits	rwx	permission
7	4 + 2 + 1	rwx	read, write and execute
6	4 + 2	rw-	read and write
5	4     + 1	r-x	read and execute
4	4	r--	read only
3	2 + 1	-wx	write and execute
2	2	-w-	write only
1	1	--x	execute only
0		---	none

For example, 754 allows:

• user class: read, write, and execute; 7 => (4 + 2 + 1)
• group class: read and execute; 5 => (4 + 1)
• others class: read only; (4)

A code permits execution if and only if it is odd (i.e. 1, 3, 5, or 7). A code permits read if and only if it is greater than or equal to 4 (i.e. 4, 5, 6, or 7). A code permits write if and only if it is 2, 3, 6, or 7.

Symbolic notation

The chmod command accepts symbolic notation that specifies how to modify the existing permissions. The command accepts a comma-separate list of specifiers like: [classes]+|-|=operations

Classes map permissions to users. A change specifier can select one class by including its symbol, multiple by including each class's symbol with no delimiter or if not specified, then all classes are selected and further the bits of umask mask will be unchanged. Class specifiers include:

Class specifiers

symbol	description
u	user: file owner
g	group: members of the file's group
o	others: users who are neither the file's owner nor members of the file's group
a	all three classes; same as ugo

As ownership is key to access control, and since the symbolic specification uses the abbreviation o, some incorrectly think that it means owner, when, in fact, it is short for others.

The change operators include:

Operators

symbol	description
+	add permissions to a class
-	remove permissions from a class
=	set the permissions for a class; grants the specified operations and denies others

Operations that can be granted or denied include:

Operation specifiers

symbol	description
r	read a regular file or list a directory's contents
w	write to a file
x	execute a regular file or recurse a directory tree
X	special execute: which is not a permission in itself but rather can be used instead of x. It applies execute permissions to directories regardless of their current permissions and applies execute permissions to a file which already has at least one execute permission bit already set (either User, Group or Others). It is only really useful when used with + and usually in combination with the -R flag for giving Group or Others access to a big directory tree without setting execute permission on normal files (such as text files), which would normally happen if you just used chmod -R a+rx ., whereas with X you can do chmod -R a+rX . instead
s	setuid/gid: Further information: § Special modes
t	sticky: Further information: § Special modes

Special modes

See also: File-system permissions

The chmod command can change the special modes of a file. The symbolic notation uses 's' to represent the setuid and setgid modes, and 't' to represent the sticky mode. The modes are only applied to the appropriate classes, regardless of whether or not other classes are specified.

Most operating systems support the specification of special modes numerically, particularly in octal, but some do not. On these systems, only the symbolic notation can be used.

Examples

Add write permission to the group class of a directory, allowing users in the same group to add files:

$ ls -ld dir # before
drwxr-xr-x   2 jsmitt  northregion 96 Apr 8 12:53 shared_dir
$ chmod g+w dir
$ ls -ld dir  # after
drwxrwxr-x   2 jsmitt  northregion 96 Apr 8 12:53 shared_dir

Remove write permission for all classes, preventing anyone from writing to the file:

$ ls -l ourBestReferenceFile
-rw-rw-r--   2 tmiller  northregion 96 Apr 8 12:53 ourBestReferenceFile
$ chmod a-w ourBestReferenceFile
$ ls -l ourBestReferenceFile
-r--r--r--   2 tmiller  northregion 96 Apr 8 12:53 ourBestReferenceFile

Set the permissions for the user and group classes to read and execute only; no write permission; preventing anyone from adding files:

$ ls -ld referenceLib
drwxr-----   2 ebowman  northregion 96 Apr 8 12:53 referenceLib
$ chmod ug=rx referenceLib
$ ls -ld referenceLib
dr-xr-x---   2 ebowman  northregion 96 Apr 8 12:53 referenceLib

Enable write for the user class while making it read-only for group and others:

$ chmod u=rw,go=r sample
$ ls -ld sample
drw-r--r--   2 oschultz  warehousing       96 Dec  8 12:53 sample

To recursively set access for the directory docs/ and its contained files:

chmod -R u+w docs/

To set user and group for read and write only and set others for read only:

chmod 664 file

To set user for read, write, and execute only and group and others for read only:

chmod 744 file

To set the sticky bit in addition to user, group and others permissions:

chmod 1755 file

To set UID in addition to user, group and others permissions:

chmod 4755 file

To set GID in addition to user, group and others permissions:

chmod 2755 file

See also

• attrib
• cacls, modifies access control lists
• chattr, changes the attributes of a file
• chgrp, changes the group of a file
• chown, changes the owner of a file
• Group identifier – Unix/POSIX system account group number; numeric value used to represent a specific group
• List of POSIX commands
• User identifier – Value identifying a user account in Unix and Unix-like operating systems
• umask, restricts permissions at file creation

External links

• chmod(1): change file modes – FreeBSD General Commands Manual
• chmod(1) – Plan 9 Programmer's Manual, Volume 1
• chmod(1) – Inferno General commands Manual
• chmod — manual page from GNU coreutils.
• GNU "Setting Permissions" manual
• CHMOD-Win 3.0 — Freeware Windows' ACL ↔ CHMOD converter.
• Beginners tutorial with on-line "live" example