diff mbox series

statx.2: Document AT_EMPTY_PATH allows using NULL instead of "" for pathname

Message ID 20240826145718.60675-2-xry111@xry111.site (mailing list archive)
State New
Headers show
Series statx.2: Document AT_EMPTY_PATH allows using NULL instead of "" for pathname | expand

Commit Message

Xi Ruoyao Aug. 26, 2024, 2:57 p.m. UTC
Link: https://git.kernel.org/torvalds/c/0ef625bba6fb
Cc: Mateusz Guzik <mjguzik@gmail.com>
Cc: Christian Brauner <brauner@kernel.org>
Cc: linux-fsdevel@vger.kernel.org
Signed-off-by: Xi Ruoyao <xry111@xry111.site>
---
 man/man2/statx.2 | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

Comments

Alejandro Colomar Aug. 26, 2024, 4:28 p.m. UTC | #1
Hi Xi!

On Mon, Aug 26, 2024 at 10:57:19PM GMT, Xi Ruoyao wrote:
> Link: https://git.kernel.org/torvalds/c/0ef625bba6fb
> Cc: Mateusz Guzik <mjguzik@gmail.com>
> Cc: Christian Brauner <brauner@kernel.org>
> Cc: linux-fsdevel@vger.kernel.org
> Signed-off-by: Xi Ruoyao <xry111@xry111.site>
> ---

Thanks for the patch.  Please see some small comments below.

>  man/man2/statx.2 | 16 +++++++++++-----
>  1 file changed, 11 insertions(+), 5 deletions(-)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index f7a06467d..741de10be 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -20,8 +20,9 @@ Standard C library
>  .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
>  .B #include <sys/stat.h>
>  .P
> -.BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags ,
> -.BI "          unsigned int " mask ", struct statx *restrict " statxbuf );
> +.BI "int statx(int " dirfd ", const char *_Nullable restrict " pathname ,
> +.BI "          int " flags ", unsigned int " mask ",
> +.BI "          struct statx *restrict " statxbuf );
>  .fi
>  .SH DESCRIPTION
>  This function returns information about a file, storing it in the buffer
> @@ -146,7 +147,7 @@ for an explanation of why this is useful.)
>  By file descriptor
>  If
>  .I pathname
> -is an empty string and the
> +is an empty string (or NULL since Linux 6.11) and the
>  .B AT_EMPTY_PATH
>  flag is specified in
>  .I flags
> @@ -164,7 +165,8 @@ is constructed by ORing together zero or more of the following constants:
>  .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
>  If
>  .I pathname
> -is an empty string, operate on the file referred to by
> +is an empty string (or NULL since Linux 6.11), operate on the file referred
> +to by

Please use semantic newlines.  In this specific case, please break the
line after the ','.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.


>  .I dirfd
>  (which may have been obtained using the
>  .BR open (2)
> @@ -604,7 +606,11 @@ nor a valid file descriptor.
>  or
>  .I statxbuf
>  is NULL or points to a location outside the process's
> -accessible address space.
> +accessible address space (except since Linux 6.11 if

You could reorder the above to be

"""
.I statxbuf
points to a location outside the process's accessible address space
or is NULL
(except ...
"""

which makes the added parenthetical to be next to the mention of NULL.

Have a lovely day!
Alex

> +.B AT_EMPTY_PATH
> +is specified in
> +.IR flags ,
> +pathname is allowed to be NULL)
>  .TP
>  .B EINVAL
>  Invalid flag specified in
> -- 
> 2.46.0
> 
>
diff mbox series

Patch

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index f7a06467d..741de10be 100644
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -20,8 +20,9 @@  Standard C library
 .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
 .B #include <sys/stat.h>
 .P
-.BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags ,
-.BI "          unsigned int " mask ", struct statx *restrict " statxbuf );
+.BI "int statx(int " dirfd ", const char *_Nullable restrict " pathname ,
+.BI "          int " flags ", unsigned int " mask ",
+.BI "          struct statx *restrict " statxbuf );
 .fi
 .SH DESCRIPTION
 This function returns information about a file, storing it in the buffer
@@ -146,7 +147,7 @@  for an explanation of why this is useful.)
 By file descriptor
 If
 .I pathname
-is an empty string and the
+is an empty string (or NULL since Linux 6.11) and the
 .B AT_EMPTY_PATH
 flag is specified in
 .I flags
@@ -164,7 +165,8 @@  is constructed by ORing together zero or more of the following constants:
 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 If
 .I pathname
-is an empty string, operate on the file referred to by
+is an empty string (or NULL since Linux 6.11), operate on the file referred
+to by
 .I dirfd
 (which may have been obtained using the
 .BR open (2)
@@ -604,7 +606,11 @@  nor a valid file descriptor.
 or
 .I statxbuf
 is NULL or points to a location outside the process's
-accessible address space.
+accessible address space (except since Linux 6.11 if
+.B AT_EMPTY_PATH
+is specified in
+.IR flags ,
+pathname is allowed to be NULL)
 .TP
 .B EINVAL
 Invalid flag specified in