Editing Chmod

{{short description|Shell command for changing access permissions of a file}}
{{lowercase title}}
{{Infobox software
| name                   = chmod
| logo                   = 
| caption                = Example usage of {{code|chmod}} command to change the specified file's permissions
| author                 = [[AT&T Bell Laboratories]]
| developer              = Various [[open-source software|open-source]] and [[commercial software|commercial]] developers
| released               = {{Start date and age|df=yes|1971|11|3}}
| latest release version = 
| latest release date    = 
| programming language   = Plan 9: [[C (programming language)|C]]
| operating system       = [[Unix]], [[Unix-like]], [[Plan 9 from Bell Labs|Plan 9]], [[Inferno (operating system)|Inferno]], [[IBM i]]
| platform               = [[Cross-platform]]
| genre                  = [[Command (computing)|Command]]
| license                = [[coreutils]]: [[GPLv3]]<br />Plan 9: [[MIT License]]
| website                = 
}}
'''{{code|chmod}}''' is a [[shell (computing)|shell]] [[command (computing)|command]] for changing [[File-system permissions|access permissions]] and special mode flags of [[Computer file|files]] (including [[Unix file type|special files]] such as [[computer directory|directories]]). The name is short for '''''ch'''ange '''mod'''e'' where ''mode'' refers to the permissions and flags collectively.<ref>The modes/permissions are shown when [[ls|listing files]] in long format.</ref><ref>{{Cite web|url=http://catcode.com/teachmod/|title=Tutorial for chmod|website=catcode.com}}</ref>

The command originated in [[Research Unix|AT&T Unix]] version 1 and was exclusive to [[Unix]] and [[Unix-like]] [[operating system]]s until it was ported to other operating systems such as [[Microsoft Windows|Windows]] (in [[UnxUtils]])<ref>{{Cite web|url=http://unxutils.sourceforge.net/|title=Native Win32 ports of some GNU utilities|website=unxutils.sourceforge.net}}</ref> and [[IBM i]].<ref>{{cite web |title=IBM System i Version 7.2 Programming Qshell |language=en |author=IBM |website=[[IBM]] |author-link=IBM |url=https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzahz/rzahzpdf.pdf?view=kc |access-date=2020-09-05 }}</ref>

In [[Unix]] and [[Unix-like]] operating systems, a [[system call]] with the same name as the command, {{mono|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 list]]s<ref>{{cite web|title=AIX 5.3 System management|url=http://www-01.ibm.com/support/knowledgecenter/#!/ssw_aix_53/com.ibm.aix.baseadmn/doc/baseadmndita/acl.htm?cp=ssw_aix_53|website=IBM knowledge Center|publisher=IBM|access-date=30 August 2015}}</ref> were added to many file systems to augment the modes controlled via {{code|chmod}}.

The implementation of {{code|chmod}} bundled in [[GNU Core Utilities|GNU coreutils]] was written by David MacKenzie and Jim Meyering.<ref>{{Cite web|url=https://linux.die.net/man/1/chmod|title=chmod(1): change file mode bits - Linux man page|website=linux.die.net}}</ref> 

==Use==

Although the syntax of the command varies somewhat by implementation, it generally accepts either a single octal value (which specifies ''all'' the mode bits on each file), or a comma-delimited list of symbolic specifiers (which describes how to change the existing mode bits of each file). The remaining arguments are a list of paths to files to be modified.<ref>{{Cite web|url=https://ss64.com/bash/chmod.html|title=chmod Man Page with examples and calculator - Linux - SS64.com|website=ss64.com}} (note that "space delimited" is a feature of the ''shell'', not of chmod itself.)</ref>

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

If a [[symbolic link]] is specified, the target of the link has its mode bits adjusted. Permissions directly associated with a symbolic link file system entry are typically not used.

===Options===

Optional, command-line options may include:
* {{code|-R}} recursive; include contained files and subdirectories of specified directories
<!--
not in Mac OS* {{code|-f}} forge ahead; processing continues if errors occur. NOT force
-->
* {{code|-v}} verbose; log changed file names

=== Octal notation ===
Given a numeric permissions argument, the {{code|chmod}} command treats it as an [[octal]] number, and replaces ''all''  the mode bits for each file. (Although 4 digits are specified, leading {{code|0}} digits can be elided.)<ref>This differs from the “C” language, where the {{code|0}} prefix for octal numbers is a remnant of its early period.</ref>

Why octal rather than decimal? <ref>Although rarely used today, during the early development of UNIX, octal was very useful because repeating groups of 3 bits were common in the physical structure of computers at the time, and these bits were easier to read & understand when encoded as octal digits, just as groups of 4 bits are easier when grouped into hexadecimal digits. The numeric expression of filesystem permissions in octal is one of the few of the few remnants of this time.</ref>

There are twelve standard mode bits, comprising 3 special bits ({{Mono|[[setuid]]}}, {{Mono|[[setgid]]}}, and {{Mono|[[Sticky bit|sticky]]}}), and 3 permission groups (controlling access by ''user'', ''group'', and ''other'') of 3 bits each (''read'', ''write'', and ''exec/scan''); each permission bit grants access if set (1) or denies access if clear (0).

As an octal digit represents a 3-bit value, the twelve mode bits can be represented as four octal digits. {{code|chmod}} accepts up to four digits and uses 0 for left digits not specified (as is normal for numeric representation). In practice, 3 digits are commonly specified since the special modes are rarely used and the user class is usually specified. 

In the context of an octal digit, each operation bit represents a numeric value: read: 4, write: 2 and execute: 1. The following table relates octal digit values to a class operations value.

{| class="wikitable"
|+ Octal digit permission
|-
! # !! bits 
! rwx
! granted operations 
|-
| 7
| {{Mono|4 + 2 + 1}} 
| {{code|rwx}}
| read, write and execute 
|-
| 6
| {{Mono|4 + 2   }}  
| {{code|rw-}}        
| read and write 
|-
| 5
| {{Mono|4 &nbsp;&nbsp;&nbsp; + 1}} 
| {{code|r-x}}
| read and execute 
|-
| 4
| {{Mono|4}} 
| {{code|r--}}                             
| read only 
|-
| 3
| {{Mono|&nbsp;&nbsp;&nbsp; 2 + 1}} 
| {{code|-wx}}
| write and execute 
|-
| 2
| {{Mono|&nbsp;&nbsp;&nbsp; 2}} 
| {{code|-w-}}
| write only 
|-
| 1
| {{Mono|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1}} 
| {{code|--x}}
| execute only 
|-
| 0
| {{Mono|}} 
| {{code|---}}       
| none 
|}

The command [[stat (Unix)|{{code|stat}}]] can report a file's permissions as octal. For example:

<syntaxhighlight lang="console">
$ stat -c %a findPhoneNumbers.sh
754
</syntaxhighlight>

The reported value, {{code|754}} indicates the following permissions:
* 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 number|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 {{code|chmod}} command accepts symbolic notation that specifies how to modify the existing permissions.<ref>{{cite web|title=AIX 5.5 Commands Reference|url=http://www-01.ibm.com/support/knowledgecenter/#!/ssw_aix_53/com.ibm.aix.cmds/doc/aixcmds1/chmod.htm?cp=ssw_aix_53%2F1-2-0-2-78|website=IBM Knowledge Center|publisher=IBM|access-date=30 August 2015}}</ref> The command accepts a comma-separate list of specifiers like: <code>[''classes'']+|-|=''operations''</code>

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.<ref>{{Cite web|url=http://teaching.idallen.com/cst8207/19w/notes/510_umask.html|title=Permissions masking with umask, chmod, 777 octal permissions|website=teaching.idallen.com}}</ref> Class specifiers include:

{| class="wikitable"
|+ Class specifiers
|-
! symbol !! description
|-
| {{Mono|u}} || user: file owner
|-
| {{Mono|g}} || group: members of the file's group
|-
| {{Mono|o}} || others: users who are neither the file's owner nor members of the file's group
|-
| {{Mono|a}} || all three classes; same as {{code|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:
{| class="wikitable"
|+ Operators
|-
! symbol !! description
|-
| {{Mono|+}} || add operations/flags
|-
| {{Mono|-}} || remove operations/flags
|-
| {{Mono|{{=}}}} || set the entire operations/flags field; grants the specified operations and denies others
|}

Operations can be specified as follows:

{| class="wikitable"
|+ Operation specifiers
|-
! symbol !! description
|-
| {{Mono|r}} || '''r'''ead a regular file or list a directory's contents
|-
| {{Mono|w}} || '''w'''rite to a file
|-
| {{Mono|x}} || e'''x'''ecute a regular file or recurse a directory tree
|-
| {{Mono|X}} || special execute: selects to apply execute to directories (regardless of their current permissions) and apply execute to files that already have at least one execute permission granted (for any class); only useful with operation {{code|+}} and usually in combination with option {{code|-R}} for giving group or others access to a directory tree without setting execute permission on regular files, which would normally happen if with {{code|chmod -R a+rx .}}; instead use {{code|chmod -R a+rX .}}
|-
| {{Mono|s}} || '''s'''etuid mode or '''s'''etgid mode
|-
| {{Mono|t}} || s'''t'''icky mode
|}

Most {{code|chmod}} implementations support the specification of the special modes in octal, but some do not which requires using the symbolic notation.

The [[ls|{{code|ls}}]] command can report file permissions in a symbolic notation that is similar to the notation used with {{code|chmod}}. {{code|ls -l}} reports permissions in a 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, group and others classes. Each position is either dash to indicate lack of permission or the single-letter abbreviation for the permission to indicate that it's granted. For example:

<syntaxhighlight lang="console">
$ ls -l findPhoneNumbers.sh
-rwxr-xr--  1 dgerman  staff  823 Dec 16 15:03 findPhoneNumbers.sh
</syntaxhighlight>

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

==Examples==
<!-- Please keep meaningful names and use examples that someone might want. DGerman
And remember: less is more. KISS -->

Add '''w'''rite permission to the '''g'''roup class of a directory, allowing users in the same group to add files:

<syntaxhighlight lang="console" highlight="3">
$ 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
</syntaxhighlight>

Remove '''w'''rite permission for '''a'''ll classes, preventing anyone from writing to the file:

<syntaxhighlight lang="console" highlight="3">
$ 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
</syntaxhighlight>

Set the permissions for the '''u'''ser and '''g'''roup classes to '''r'''ead and e'''x'''ecute only; no '''w'''rite permission; preventing anyone from adding files:

<syntaxhighlight lang="console" highlight="3">
$ 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
</syntaxhighlight>

Enable '''w'''rite for the '''u'''ser class while making it '''r'''ead-only for '''g'''roup and others:

<syntaxhighlight lang="console">
$ chmod u=rw,go=r sample
$ ls -ld sample
drw-r--r--   2 oschultz  warehousing       96 Dec  8 12:53 sample
</syntaxhighlight>

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

<code>chmod -R u+w docs/</code>

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

<code>chmod 664 file</code>

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

<code>chmod 744 file</code>

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

<code>chmod 1755 file</code>

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

<code>chmod 4755 file</code>

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

<code>chmod 2755 file</code>

==See also==
* <code>[[attrib]]</code>
* <code>[[cacls]]</code>, modifies access control lists
* <code>[[chattr]]</code>, changes the attributes of a file
* <code>[[chgrp]]</code>, changes the group of a file
* <code>[[chown]]</code>, changes the owner of a file
* {{Annotated link|Group identifier}}
* {{Annotated link|List of POSIX commands}}
* {{Annotated link|User identifier}}
* <code>[[umask]]</code>, restricts permissions at file creation

==References==
{{Reflist}}

==External links==
{{Wikibooks|Guide to Unix|Commands}}
* {{man|1|chmod|FreeBSD|change file modes}}
* {{man|1|chmod|Plan 9}}
* {{man|1|chmod|Inferno}}
* [https://www.gnu.org/software/coreutils/manual/html_node/chmod-invocation.html <code>chmod</code>] — manual page from [[GNU]] [[coreutils]].
* [https://www.gnu.org/software/coreutils/manual/html_node/Setting-Permissions.html GNU "Setting Permissions" manual]
* [http://neosmart.net/dl.php?id=4 CHMOD-Win 3.0] &mdash; Freeware Windows' ACL ↔ CHMOD converter.
* [http://catcode.com/teachmod/index.html Beginners tutorial with on-line "live" example]

{{Unix commands}}
{{Plan 9 commands}}
{{Core Utilities commands}}
{{Use dmy dates|date=January 2018}}

[[Category:File system permissions]]
[[Category:Operating system security]]
[[Category:Standard Unix programs]]
[[Category:Unix file system-related software]]
[[Category:Unix SUS2008 utilities]]
[[Category:Plan 9 commands]]
[[Category:Inferno (operating system) commands]]
[[Category:IBM i Qshell commands]]