On Thu, Aug 29, 2024 at 7:44 PM Alejandro Colomar <alx@xxxxxxxxxx> wrote:
Hi Elliott,
On Tue, Aug 27, 2024 at 03:07:54PM GMT, enh wrote:
> oh, i can definitely make a start...
>
> (i was going to at least send you the easiest patch, but then i
> realized even there there's a bit of a bikeshed opportunity, so i'll
> just give you all the pieces and let you decide what to do with them!)
Thanks!
>
> so i think we have these things to say:
>
> 1. AT_SYMLINK_NOFOLLOW _is_ supported for fchmodat(2).
> 2. but only since Linux 6.6 (except see 4).
> 3. there's no mention of lchmod().
> 4. that function is very old, but it doesn't actually work on glibc
> until 2.32 (https://sourceware.org/bugzilla/show_bug.cgi?id=14578#c16)
> where it uses the O_PATH trick that musl and bionic also use (and so
> doesn't need Linux 6.6).
>
> heh, actually trying to write the bits down is probably easiest done
> as a diff anyway...
>
> diff --git a/man/man2/chmod.2 b/man/man2/chmod.2
> index ae53fe3c9..c6c54eeca 100644
> --- a/man/man2/chmod.2
> +++ b/man/man2/chmod.2
> @@ -11,7 +11,7 @@
> .\"
> .TH chmod 2 (date) "Linux man-pages (unreleased)"
> .SH NAME
> -chmod, fchmod, fchmodat \- change permissions of a file
> +chmod, fchmod, lchown, fchmodat \- change permissions of a file
> .SH LIBRARY
> Standard C library
> .RI ( libc ,\~ \-lc )
> @@ -21,6 +21,7 @@ Standard C library
> .P
> .BI "int chmod(const char *" pathname ", mode_t " mode );
> .BI "int fchmod(int " fd ", mode_t " mode );
> +.BI "int lchmod(const char *" pathname ", mode_t " mode );
Does lchmod() need any feature test macros?
done.
> .P
> .BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
> .B #include <sys/stat.h>
> @@ -60,9 +61,10 @@ Feature Test Macro Requirements for glibc (see
> .fi
> .SH DESCRIPTION
> The
> -.BR chmod ()
> -and
> +.BR chmod (),
> .BR fchmod ()
We use Oxford comma.
done.
> +and
> +.BR lchmod ()
> system calls change a file's mode bits.
> (The file mode consists of the file permission bits plus the set-user-ID,
> set-group-ID, and sticky bits.)
> @@ -76,6 +78,11 @@ which is dereferenced if it is a symbolic link.
> .BR fchmod ()
> changes the mode of the file referred to by the open file descriptor
> .IR fd .
> +.IP \[bu]
> +.BR lchmod ()
> +is like
> +.BR chmod (),
> +but does not dereference symbolic links.
> .P
> The new file mode is specified in
> .IR mode ,
> @@ -203,8 +210,9 @@ can either be 0, or include the following flag:
> If
> .I pathname
> is a symbolic link, do not dereference it:
> -instead operate on the link itself.
> -This flag is not currently implemented.
> +instead operate on the link itself,
> +like
> +.BR lchmod ().
> .P
> See
> .BR openat (2)
> @@ -285,6 +293,7 @@ is a file descriptor referring to a file other
Would you mind checking this?:
$ head -n11 <CONTRIBUTING.d/git
Name
Git - instructions for configuring git(1)
Description
git-diff(1), gitattributes(5)
To produce useful hunk contexts in manual pages, we need to hack
git(1)'s idea of a function name, and also to tell git what is a
manual page.
$ git config --global diff.man.xfuncname '^\.S[SHsh] .*$';
$ echo '*.[0-9]* diff=man' >>~/.config/git/attributes;
It helps reviewing diffs for manual pages. :)
~/man-pages$ echo '*.[0-9]* diff=man' >>~/.git/attributes;
-bash: /usr/local/google/home/enh/.git/attributes: No such file or directory
-bash: /usr/local/google/home/enh/.git/attributes: No such file or directory
i assume this is meant to be
~/man-pages$ echo '*.[0-9]* diff=man' >>~/.gitattributes;
instead?
> than a directory.
> specified
> .BR AT_SYMLINK_NOFOLLOW ,
> which is not supported.
> +(See C library/kernel differences.)
> .TP
> .B EPERM
> The effective UID does not match the owner of the file,
> @@ -310,12 +319,22 @@ This interface differs from the underlying Linux
> system call, which does
> have a
> .I flags
> argument.
> +.P
> +Linux 6.6 added the
> +.BR fchmodat2 ()
> +system call with the POSIX flags argument.
> .SS glibc notes
> On older kernels where
> -.BR fchmodat ()
> +.BR fchmodat2 ()
> is unavailable, the glibc wrapper function falls back to the use of
> -.BR chmod ().
> -When
> +.BR fchmodat ()
> +when no flags are supplied,
> +or to
> +.BR chmod ()
> +otherwise.
> +In the
> +.BR chmod ()
> +fallback, if
> .I pathname
> is a relative pathname,
> glibc constructs a pathname based on the symbolic link in
>
> something along those lines?
Sounds good. I'd like to also add entries in HISTORY for lchmod() and
fchmodat2(). And STANDARDS should also be updated.
done.
Have a lovely night!
Alex
--
<https://www.alejandro-colomar.es/>
diff --git a/man/man2/chmod.2 b/man/man2/chmod.2
index ae53fe3c9..3085840a2 100644
--- a/man/man2/chmod.2
+++ b/man/man2/chmod.2
@@ -11,7 +11,7 @@
.\"
.TH chmod 2 (date) "Linux man-pages (unreleased)"
.SH NAME
-chmod, fchmod, fchmodat \- change permissions of a file
+chmod, fchmod, lchown, fchmodat \- change permissions of a file
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
@@ -21,6 +21,7 @@ Standard C library
.P
.BI "int chmod(const char *" pathname ", mode_t " mode );
.BI "int fchmod(int " fd ", mode_t " mode );
+.BI "int lchmod(const char *" pathname ", mode_t " mode );
.P
.BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
.B #include <sys/stat.h>
@@ -51,6 +52,12 @@ Feature Test Macro Requirements for glibc (see
.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
.fi
.P
+.BR lchmod ():
+.nf
+ Since glibc 2.5:
+ _DEFAULT_SOURCE
+.fi
+.P
.BR fchmodat ():
.nf
Since glibc 2.10:
@@ -60,9 +67,10 @@ Feature Test Macro Requirements for glibc (see
.fi
.SH DESCRIPTION
The
-.BR chmod ()
+.BR chmod (),
+.BR fchmod (),
and
-.BR fchmod ()
+.BR lchmod ()
system calls change a file's mode bits.
(The file mode consists of the file permission bits plus the set-user-ID,
set-group-ID, and sticky bits.)
@@ -76,6 +84,11 @@ which is dereferenced if it is a symbolic link.
.BR fchmod ()
changes the mode of the file referred to by the open file descriptor
.IR fd .
+.IP \[bu]
+.BR lchmod ()
+is like
+.BR chmod (),
+but does not dereference symbolic links.
.P
The new file mode is specified in
.IR mode ,
@@ -203,8 +216,9 @@ can either be 0, or include the following flag:
If
.I pathname
is a symbolic link, do not dereference it:
-instead operate on the link itself.
-This flag is not currently implemented.
+instead operate on the link itself,
+like
+.BR lchmod ().
.P
See
.BR openat (2)
@@ -285,6 +299,7 @@ is a file descriptor referring to a file other than a directory.
specified
.BR AT_SYMLINK_NOFOLLOW ,
which is not supported.
+(See C library/kernel differences.)
.TP
.B EPERM
The effective UID does not match the owner of the file,
@@ -310,12 +325,22 @@ This interface differs from the underlying Linux system call, which does
have a
.I flags
argument.
+.P
+Linux 6.6 added the
+.BR fchmodat2 ()
+system call with the POSIX flags argument.
.SS glibc notes
On older kernels where
-.BR fchmodat ()
+.BR fchmodat2 ()
is unavailable, the glibc wrapper function falls back to the use of
-.BR chmod ().
-When
+.BR fchmodat ()
+when no flags are supplied,
+or to
+.BR chmod ()
+otherwise.
+In the
+.BR chmod ()
+fallback, if
.I pathname
is a relative pathname,
glibc constructs a pathname based on the symbolic link in
@@ -324,7 +349,16 @@ that corresponds to the
.I dirfd
argument.
.SH STANDARDS
+.TP
+.BR chmod ()
+.TQ
+.BR fchmod ()
+.TQ
+.BR fchmodat ()
POSIX.1-2008.
+.TP
+.BR lchmod ()
+Linux.
.SH HISTORY
.TP
.BR chmod ()
@@ -336,6 +370,9 @@ POSIX.1-2008.
POSIX.1-2008.
Linux 2.6.16,
glibc 2.4.
+.TP
+.BR lchmod ()
+Linux 2.6.16, glibc 2.5.
.SH SEE ALSO
.BR chmod (1),
.BR chown (2),
