Clarify docs re mode's octal representation (#44410)

* Clarify docs re mode's octal representation

I changed the language about how to use mode to make it more obvious
that using "01777" is not a typo, because the leading zero is not meant
to reflect the way that number might have been given on a command line.
See also: issues #5409 #9196 #11385 #13115 #18952 #23491 #23521
This commit is contained in:
Todd Walton 2018-08-29 16:12:32 -04:00 committed by Alicia Cozine
commit 1247f4a464
4 changed files with 10 additions and 9 deletions

View file

@ -60,9 +60,9 @@ options:
mode:
description:
- "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that
modes are actually octal numbers. You must either specify the leading zero so that
Ansible's YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
(like C('644') or C('0644') so Ansible receives a string and can do its own conversion from
modes are actually octal numbers. You must either add a leading zero so that Ansible's
YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
(like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from
string into number. Giving Ansible a number without following one of these rules will end
up with a decimal number which will have unexpected results. As of version 1.8, the mode
may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). As of

View file

@ -103,11 +103,12 @@ options:
'''
EXAMPLES = '''
# change file ownership, group and mode. When specifying mode using octal numbers, first digit should always be 0.
# change file ownership, group and mode
- file:
path: /etc/foo.conf
owner: foo
group: foo
# when specifying mode using octal numbers, add a leading 0
mode: 0644
- file:
path: /work

View file

@ -98,9 +98,9 @@ options:
mode:
description:
- "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that
modes are actually octal numbers. You must either specify the leading zero so that
Ansible's YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
(like C('644') or C('0644') so Ansible receives a string and can do its own conversion from
modes are actually octal numbers. You must either add a leading zero so that Ansible's
YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
(like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from
string into number. Giving Ansible a number without following one of these rules will end
up with a decimal number which will have unexpected results. As of version 1.8, the mode
may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). As of

View file

@ -27,8 +27,8 @@ options:
mode:
description:
- "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
You must either specify the leading zero so that Ansible's YAML parser knows it is an octal
number (like C(0644) or C(01777)) or quote it (like C('644') or C('0644') so Ansible
You must either add a leading zero so that Ansible's YAML parser knows it is an octal
number (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible
receives a string and can do its own conversion from string into number. Giving Ansible a number
without following one of these rules will end up with a decimal number which will have unexpected results.
As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r))."