os: ambiguous documentation of type FileMode

[mib-kd743naq]

What version of Go are you using (go version)?

N/A

Does this issue reproduce with the latest release?

Yes ( latest document online )

What operating system and processor architecture are you using (go env)?

N/A

What did you do?

Read documentation of the FileMode bitfields

What did you expect to see?

Either

• ...The values of the lowest 9 bits should be considered part of the public API...
  OR
• ...The values of any of the 32 bits already defined in the const listing below should be considered part of the public API...

What did you see instead?

• ...The values of these bits should be considered part of the public API...

The documentation as currently written is clearly open to interpretation. Further discussion: https://botbot.me/freenode/go-nuts/2018-05-16/?msg=100120706&page=5

[ianlancetaylor]

I guess the text could be read to be ambiguous. When the comment says "these bits should be considered part of the public API" it refers to all the bits, not just the nine least-significant bits.

[mib-kd743naq]

I guess the text could be read to be ambiguous ... it refers to all the bits, not just the nine least-significant bits.

Note that @GinjaNinja32 read the documentation exactly the opposite way, so a fix is clearly in order ;)

[bcmills]

In context, I would interpret it to mean:
“The numeric values of the single-bit FileMode constants should be considered part of the public API […].”

[vikramcse]

@bcmills @ianlancetaylor

The defined file mode bits are the most significant bits of the FileMode. The nine least-significant bits are the standard Unix rwxrwxrwx permissions. The numeric values of the single-bit FileMode constants should be considered part of the public API and may be used in wire protocols or disk representations: they must not be changed, although new bits might be added.

Should I raise CL with above comment?

[ianlancetaylor]

I think we should separate the non-single-bit constants into a separate const block and adjust the comment as needed to make clear which ones can not change.

In truth changing any of the constant values would break Go 1 compatibility but it does make sense to clarify that the single-bit flags especially can't be changed.

[Windsooon]

How about

The nine least-significant bits are the standard Unix rwxrwxrwx permissions (permissions bits). Permissions bits should be considered part of the public API and may be used in wire protocols or disk representations which must not be changed, although new bits might be added.

[mib-kd743naq]

@bcmills @ianlancetaylor this ticket is over a year old. Could we bump it a bit? Thanks!

[ianlancetaylor]

Want to send in a pull request?

[Windsooon]

I can send a PR is we are ok with my suggestion.

[ianlancetaylor]

Sounds reasonable, thanks.

[mib-kd743naq]

@Windsooon if you are referring literally to the text in #25422 (comment), it is insufficient to address the original reason I opened this PR. It is clear that the low 9 bits are "set in stone". The original text and also your suggested text do not answer the question:

• Is there an explicit promise that the POSIX-expressing bits at positions 32 ( is directory ), 28 ( is symlink ), 27 ( is block/char device node ), 26 ( is pipe ), 25 ( is socket ), 24 ( has setuid-perm ), 23 ( has setgid-perm ), 22 ( what type of device node when bit 27 is set ), 22 ( has sticky-perm ) are guaranteed to "be correct" for all systems golang currently builds on?

( afaik golang does not work on systems without at least rudimentary POSIX-ish support )

[ianlancetaylor]

@mib-kd743naq The os package is responsible for adjusting the underlying file information to use the exported mode bits.

[mib-kd743naq]

The os package is responsible for adjusting the underlying file information

I gathered as much ;) I simply wanted to point out again that a fix which only discusses "the low 9 bits" is not sufficient. I haven't tried to send a PR myself as CLA's are hard :(

[gopherbot]

Change https://golang.org/cl/191313 mentions this issue: os: fix ambiguous documentation of type FileMode

[mib-kd743naq]

@bcmills @ianlancetaylor I am really confused... Based on your comments #25422 (comment) and #25422 (comment) all currently defined bits out of the 32 are stable and can be relied upon never changing ( specifically bits 32, 28, 27/22, 26, 25, 24, 21 )

Yet commit https://go-review.googlesource.com/c/go/+/191313/1/src/os/types.go explicitly changes the text to read:

The values of the lowest 9 bits should be considered ...

So which one is it? Any defined out of the 32, or just the lowest 9?

[ianlancetaylor]

You're right, I'm confused too. The text in #25422 (comment) looks more or less correct. The text in #25422 (comment) looks misleading. I was reading the latter comment out of context.