install modes should not apply sticky bit to files

This is generally a bad idea, e.g. it causes OSError on freebsd.

It also gets ignored by solaris and thus causes unittest failures.

The proper solution is to simply reject any attempt to set this, and log a
warning.

The install_emptydir function does apply the mode as well, and since it
is a directory it actually does something. This is the only place where
we don't reset the mode.

Although install_subdir also installs directories, and in theory it
could set the mode as well, that would be a new feature. Also it doesn't
provide much granularity and has mixed semantics with files. Better to
let people use install_emptydir + install_subdir.

Fixes #5902

1 files changed, 14 insertions, 0 deletions

diff --git a/docs/markdown/snippets/deprecated_install_mode_sticky.md b/docs/markdown/snippets/deprecated_install_mode_sticky.md
new file mode 100644
index 0000000..3168df6
--- /dev/null
+++ b/docs/markdown/snippets/deprecated_install_mode_sticky.md
@@ -0,0 +1,14 @@
+## various `install_*` functions no longer handle the sticky bit
+
+It is not possible to portably grant the sticky bit to a file, and where
+possible, it doesn't do anything. It is not expected that any users are using
+this functionality.
+
+Variously:
+- on Linux, it has no meaningful effect
+- on Solaris, attempting to set the permission bit is silently ignored by the OS
+- on FreeBSD, attempting to set the permission bit is an error
+
+Attempting to set this permission bit in the `install_mode:` kwarg to any
+function other than [[install_emptydir]] will now result in a warning, and the
+permission bit being ignored.