[PATCH v2] man/man2/getdents.2: Document system call interface of getdents64

[PATCH v2] man/man2/getdents.2: Document system call interface of getdents64

[vursc]

The count argument of the getdents64 system call is assumed to not exceed
INT_MAX. The glibc function accepts a size_t and passes INT_MAX to the kernel
if count exceeds INT_MAX.

Also document the glibc definition of the linux_dirent64 structure as dirent64.

Signed-off-by: vursc <vursc@vursc.org>
---
 man/man2/getdents.2 | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/man/man2/getdents.2 b/man/man2/getdents.2
index 8c5bbebbc..48bdf7bd7 100644
--- a/man/man2/getdents.2
+++ b/man/man2/getdents.2
@@ -42,7 +42,6 @@ These are not the interfaces you are interested in.
 Look at
 .BR readdir (3)
 for the POSIX-conforming C library interface.
-This page documents the bare kernel system call interfaces.
 .SS getdents()
 The system call
 .BR getdents ()
@@ -216,10 +215,29 @@ using
 .BR syscall (2).
 In that case you will need to define the
 .I linux_dirent
-or
-.I linux_dirent64
 structure yourself.
 .P
+The
+.B getdents64
+system call accepts an
+.B unsigned int
+argument
+.I count
+and assumes that
+.I count
+does not exceed
+.BR INT_MAX .
+The glibc wrapper function sets
+.I count
+to
+.B INT_MAX
+if it exceeds
+.BR INT_MAX .
+glibc defines the
+.I linux_dirent64
+structure as
+.IR dirent64 .
+.P
 Probably, you want to use
 .BR readdir (3)
 instead of these system calls.
-- 
2.53.0

[PATCH v3] man/man2/getdents.2: Document system call interface of getdents64

[vursc]

The count argument of the getdents64 system call is assumed to not exceed
INT_MAX. The glibc function accepts a size_t and passes INT_MAX to the kernel
if count exceeds INT_MAX.

Also document the dirent64 structure in glibc.

Signed-off-by: vursc <vursc@vursc.org>
---
 man/man2/getdents.2 | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/man/man2/getdents.2 b/man/man2/getdents.2
index 8c5bbebbc..de91f3800 100644
--- a/man/man2/getdents.2
+++ b/man/man2/getdents.2
@@ -42,7 +42,6 @@ These are not the interfaces you are interested in.
 Look at
 .BR readdir (3)
 for the POSIX-conforming C library interface.
-This page documents the bare kernel system call interfaces.
 .SS getdents()
 The system call
 .BR getdents ()
@@ -216,10 +215,31 @@ using
 .BR syscall (2).
 In that case you will need to define the
 .I linux_dirent
-or
-.I linux_dirent64
 structure yourself.
 .P
+The
+.B getdents64
+system call accepts an
+.B unsigned int
+argument
+.I count
+and assumes that
+.I count
+does not exceed
+.BR INT_MAX .
+The glibc wrapper function sets
+.I count
+to
+.B INT_MAX
+if it exceeds
+.BR INT_MAX .
+glibc defines a
+.I dirent64 
+structure, which is similar to
+.I linux_dirent64
+but with a 256-byte
+.IR d_name .
+.P
 Probably, you want to use
 .BR readdir (3)
 instead of these system calls.
-- 
2.53.0

Re: [PATCH v3] man/man2/getdents.2: Document system call interface of getdents64

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2035 bytes --]

Hi vursc,

On 2026-04-06T09:21:14+0000, vursc wrote:
> The count argument of the getdents64 system call is assumed to not exceed
> INT_MAX. The glibc function accepts a size_t and passes INT_MAX to the kernel
> if count exceeds INT_MAX.
> 
> Also document the dirent64 structure in glibc.
> 
> Signed-off-by: vursc <vursc@vursc.org>

Thanks!  I applied the patch.  Just FYI, there was a warning:

	Applying: man/man2/getdents.2: Document system call interface of getdents64
	.../rebase-apply/patch:42: trailing whitespace.
	.I dirent64 
	warning: 1 line adds whitespace errors.

I've amended it (it was just a trailing white space).

> ---
>  man/man2/getdents.2 | 26 +++++++++++++++++++++++---
>  1 file changed, 23 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man2/getdents.2 b/man/man2/getdents.2
> index 8c5bbebbc..de91f3800 100644
> --- a/man/man2/getdents.2
> +++ b/man/man2/getdents.2
> @@ -42,7 +42,6 @@ These are not the interfaces you are interested in.
>  Look at
>  .BR readdir (3)
>  for the POSIX-conforming C library interface.
> -This page documents the bare kernel system call interfaces.
>  .SS getdents()
>  The system call
>  .BR getdents ()
> @@ -216,10 +215,31 @@ using
>  .BR syscall (2).
>  In that case you will need to define the
>  .I linux_dirent
> -or
> -.I linux_dirent64
>  structure yourself.
>  .P
> +The
> +.B getdents64

I've changed this to

	.BR getdents64 ()


Have a lovely night!
Alex

> +system call accepts an
> +.B unsigned int
> +argument
> +.I count
> +and assumes that
> +.I count
> +does not exceed
> +.BR INT_MAX .
> +The glibc wrapper function sets
> +.I count
> +to
> +.B INT_MAX
> +if it exceeds
> +.BR INT_MAX .
> +glibc defines a
> +.I dirent64 
> +structure, which is similar to
> +.I linux_dirent64
> +but with a 256-byte
> +.IR d_name .
> +.P
>  Probably, you want to use
>  .BR readdir (3)
>  instead of these system calls.
> -- 
> 2.53.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]