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 and 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.

Syntax

Although the syntax of the command varies somewhat by implementation, it generally is:

chmod [options] mode[,mode] file [file ...]

Where mode is either a symbolic or a numeric access specification (see below) and with options:

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

Semantics

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

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

Permission notation

To view the permission settings of a file or directory, 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 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

Numerical permissions

The chmod numerical format accepts up to four digits. The three rightmost digits define permissions for the file user, the group, and others. The optional leading digit, when 4 digits are given, specifies the special setuid, setgid, and sticky flags. Each digit of the three rightmost digits represents a binary value, which controls the "read", "write" and "execute" permissions respectively. A value of 1 means a class is allowed that action, while a 0 means it is disallowed.

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

For example, 754 would allow:

• "read" (4), "write" (2), and "execute" (1) for the User class; i.e., 7 (4 + 2 + 1).
• "read" (4) and "execute" (1) for the Group class; i.e., 5 (4 + 1).
• Only "read" (4) for the Others class.

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

Numeric example

Change permissions to permit the programmers update of a file:

$ ls -l File
-rw-r--r--  1 jsmith programmers 57 Jul  3 10:13  File
$ chmod 664 File
$ ls -l File
-rw-rw-r--  1 jsmith programmers 57 Jul  3 10:13  File

Since the setuid, setgid and sticky bits are not specified, this is equivalent to:

$ chmod 0664 File

See also: Numeric notation of file system permissions

Symbolic modes

See also: Symbolic notation of file system permissions

The chmod command also accepts a finer-grained symbolic notation, which allows modifying specific modes while leaving other modes untouched. The symbolic mode is composed of three components, which are combined to form a single string of text:

$ chmod [references][operator][modes] file ...

Classes of users are used to distinguish to whom the permissions apply. If no classes are specified "all" is implied. The classes are represented by one or more of the following letters:

Reference	Class	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	all three of the above, same as ugo
(empty)	default	same as "all", except that bits in the umask will be unchanged

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 chmod command uses an operator to specify how the modes of a file should be adjusted. The following operators are accepted:

Operator	Description
+	adds the specified modes to the specified classes
-	removes the specified modes from the specified classes
=	the modes specified are to be made the exact modes for the specified classes

The modes indicate which permissions are to be granted or removed from the specified classes. There are three basic modes which correspond to the basic permissions:

Mode	Name	Description
r	read	read a file or list a directory's contents
w	write	write to a file or directory
x	execute	execute a 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

Multiple changes can be specified by separating multiple symbolic modes with commas (without spaces). If a user is not specified, chmod will check the umask and the effect will be as if "a" was specified except bits that are set in the umask are not affected.

Symbolic examples

• Add write permission (w) to the Group's (g) access modes of a directory, allowing users in the same group to add files:

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

• Remove write permissions (w) for all classes (a), 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 the Group (ug) to read and execute (rx) only (no write permission) on referenceLib, 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

• Add the read and write permissions to the user and group classes of a file or directory named sample:

$ chmod ug+rw sample
$ ls -ld sample
drw-rw----   2 rsanchez  budget       96 Dec  8 12:53 sample

• Remove all permissions, allowing no one to read, write, or execute the file named sample to no useful end.

$ chmod a-rwx sample
$ ls -l sample
----------   2 rswven  planning       96 Dec  8 12:53 sample

• Change the permissions for the user and the group to read and execute only (no write permission) on sample.

$ # Sample file permissions before command
$ ls -ld sample
drw-rw----   2 oschultz  warehousing       96 Dec  8 12:53 NY_DBs
$ chmod ug=rx sample
$ ls -ld sample
dr-xr-x---   2 oschultz  warehousing       96 Dec  8 12:53 NJ_DBs

• Set the item writable for the user while making it read-only for anyone else with only one command:

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

Special modes

See also: File-system permissions

The chmod command is also capable of changing the additional permissions or special modes of a file or directory. The symbolic modes use '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 modes can be used.

Examples

To enable read permission for all classes (user, group and others):

chmod a+r file

To disable execute permission for all classes:

chmod a-x file

To enables read and execute permissions for all classes:

chmod a+rx file

To enable read and write for user, enable read for group, and disable all access for others:

chmod u=rw,g=r,o= file

To enable read and write for user and group:

chmod ug=rw file

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

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 or directory
• chgrp, changes the group of a file or directory
• chown, changes the owner of a file or directory
• 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 or directory 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