docs: Permissions.readonly() also ignores root user special permissions

[intgr]

The root user can write to files without any (write) permission bits set. But this is not taken into account by std::fs::Permissions.readonly().

The rustdoc for readonly() also mentions shortcomings later:

On Unix-based platforms this checks if any of the owner, group or others write permission bits are set. It does not check if the current user is in the file’s assigned group. It also does not check ACLs.

But since this part already clarifies how it works -- it checks write permission bits -- I think it's not necessary to repeat the root user shortcomings here.

[rustbot]

r? @ChrisDenton

rustbot has assigned @ChrisDenton.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[ChrisDenton]

I'm not really sure about this. I agree it's technically redundant but we've been really keen to emphasise the shortcomings of readonly/set_readonly as it can be a footgun, especially to those who aren't super familiar with the posix permissions model.

maybe @the8472 has some thoughts here?

[the8472]

I think it'd be better to make this a broader statement that says that it only looks at a very limited set of properties of the file metadata and is not an accurate "will this file be non-writable" test and then refer to the platform-specific notes for more details.

E.g. on unix you can also create a file as read-only but have a writable file descriptor open.

[the8472]

that it only looks at a very limited set of properties of the file metadata and is not an accurate

And "not accurate" can be expanded to "has both false positives and false negatives".

[Dylan-DPC]

@intgr @the8472 what's the status of this? thanks

[intgr]

I'm sorry, I have somehow missed GitHub notifications about this PR.

It makes sense to make the 'Note' section shorter and explain this caveat in the 'Unix' section instead. Will change.

[intgr]

I have pushed changes:

• I moved the general statement up into the Note section: "cannot be relied upon to predict whether attempts to read or write the file will actually succeed"
• Moved the note about root user down into the Unix section

[ChrisDenton]

Thanks!

@bors r+ rollup

[bors]

📌 Commit edfdfbe has been approved by ChrisDenton

It is now in the queue for this repository.