Skip to contentSkip to conversation

process_madvise.2: Document the glibc wrapper

PATCH In review Alejandro Colomar 2 participants 4 messages Feb 25, 2024 – Feb 27, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Alejandro Colomar

author maintainer
#0 lore raw

PATCH 1/2 process_madvise.2: Document the glibc wrapper

$ grepc -n process_madvise /usr/include/
/usr/include/x86_64-linux-gnu/bits/mman_ext.h:25:
extern __ssize_t process_madvise (int __pid_fd, const struct iovec *__iov,
				  size_t __count, int __advice,
				  unsigned __flags)
  __THROW;
---
 man2/process_madvise.2 | 20 +++++---------------
 1 file changed, 5 insertions(+), 15 deletions(-)
man2/process_madvise.2 +5 -15
index 53fd57598..ed8739663 100644
@@ -13,23 +13,12 @@ .SH LIBRARY
 .RI ( libc ", " \-lc )
 .SH SYNOPSIS
 .nf
-.BR "#include <sys/mman.h>" "      /* Definition of " MADV_* " constants */"
-.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
-.BR "#include <sys/uio.h>" "       /* Definition of " "struct iovec" " type */"
-.B #include <unistd.h>
+.B #include <sys/mman.h>
 .P
-.BI "ssize_t syscall(SYS_process_madvise, int " pidfd ,
-.BI "                const struct iovec *" iovec ", size_t " vlen \
-", int " advice ,
-.BI "                unsigned int " flags ");"
+.BI "ssize_t process_madvise(int " pidfd ", const struct iovec *" iovec ,
+.BI "                        size_t " vlen ", int " advice \
+", unsigned int " flags );
 .fi
-.P
-.IR Note :
-glibc provides no wrapper for
-.BR process_madvise (),
-necessitating the use of
-.BR syscall (2).
-.\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380>
 .SH DESCRIPTION
 The
 .BR process_madvise ()
@@ -187,6 +176,7 @@ .SH STANDARDS
 Linux.
 .SH HISTORY
 Linux 5.10.
+glibc 2.36.
 .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
 .P
 Support for this system call is optional,
Signature · 1 line
2.43.0
author maintainer
#1 lore raw

PATCH 2/2 process_madvise.2: Rename parameter, and use array syntax

---
 man2/process_madvise.2 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
man2/process_madvise.2 +7 -7
index ed8739663..2d91924ca 100644
@@ -15,8 +15,8 @@ .SH SYNOPSIS
 .nf
 .B #include <sys/mman.h>
 .P
-.BI "ssize_t process_madvise(int " pidfd ", const struct iovec *" iovec ,
-.BI "                        size_t " vlen ", int " advice \
+.BI "ssize_t process_madvise(int " pidfd ", const struct iovec " iovec [. n ],
+.BI "                        size_t " n ", int " advice \
 ", unsigned int " flags );
 .fi
 .SH DESCRIPTION
@@ -27,7 +27,7 @@ .SH DESCRIPTION
 It provides the advice for the address ranges described by
 .I iovec
 and
-.IR vlen .
+.IR n .
 The goal of such advice is to improve system or application performance.
 .P
 The
@@ -43,7 +43,7 @@ .SH DESCRIPTION
 structures, described in
 .BR iovec (3type).
 .P
-.I vlen
+.I n
 specifies the number of elements in the array of
 .I iovec
 structures.
@@ -80,12 +80,12 @@ .SH DESCRIPTION
 specified as 0.
 .P
 The
-.I vlen
+.I n
 and
 .I iovec
 arguments are checked before applying any advice.
 If
-.I vlen
+.I n
 is too big, or
 .I iovec
 is invalid,
@@ -152,7 +152,7 @@ .SH ERRORS
 value.
 .TP
 .B EINVAL
-.I vlen
+.I n
 is too large.
 .TP
 .B ENOMEM
Signature · 1 line
2.43.0
#2 lore raw
In reply to Alejandro Colomar

Hi!

man2/process_madvise.2 .SH STANDARDS · line 180

Quoted 10 lines · Alejandro Colomar
man2/process_madvise.2 +1 -0
index 53fd57598..ed8739663 100644
@@ -187,6 +176,7 @@ .SH STANDARDS
 Linux.
 .SH HISTORY
 Linux 5.10.
+glibc 2.36.
 .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc

This commit id seems to belong to Linux, so perhaps keep it after the Linux version reference?

Thanks,
Guillem

author maintainer
#3 lore raw

Hi!

Quoted 16 lines · Guillem Jover

Hi!

man2/process_madvise.2 .SH STANDARDS · line 180

Quoted 10 lines · Alejandro Colomar
man2/process_madvise.2 +1 -0
index 53fd57598..ed8739663 100644
@@ -187,6 +176,7 @@ .SH STANDARDS
 Linux.
 .SH HISTORY
 Linux 5.10.
+glibc 2.36.
 .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc

This commit id seems to belong to Linux, so perhaps keep it after the Linux version reference?

Yup! Thanks. Since I already pushed that to master, I've written a fix. I'll push it tomorrow, if it looks good to you.

Havea lovely night!
Alex

---

commit 22c0efa9a291c666c0b44a74b9a7ff4a04a7f674 (HEAD -> contrib)

Author: Alejandro Colomar <[email protected]>
Date:   Wed Feb 28 00:10:23 2024 +0100

process_madvise.2: Fix comments about commit ids

Move the comment about the Linux commit id, specify that it's a Linux commit, and add the glibc commit id too.

man2/process_madvise.2 +2 -1
index 2d91924ca..2c9f0b3f9 100644
@@ -176,8 +176,9 @@ .SH STANDARDS
 Linux.
 .SH HISTORY
 Linux 5.10.
+.\" Linux commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
 glibc 2.36.
-.\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
+.\" glibc commit d19ee3473d68ca0e794f3a8b7677a0983ae1342e
 .P
 Support for this system call is optional,
 depending on the setting of the
Signature · 2 lines
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.