* [PATCH 0/2] Normalize notes about missing glibc wrappers
@ 2020-12-29 14:38 Alejandro Colomar
2020-12-29 14:39 ` [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing " Alejandro Colomar
` (2 more replies)
0 siblings, 3 replies; 21+ messages in thread
From: Alejandro Colomar @ 2020-12-29 14:38 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, linux-man, Ganimedes Colomar
Hi Michael,
Here are 2 patches my brother and I prepared together.
There are still some pages that we couldn't find with grep,
so I'll send you more patches continuing these 2 as I find them
while fixing other things.
Cheers,
Alex
Ganimedes Colomar (2):
Various pages: Normalize SYNOPSIS notes about non-existing glibc
wrappers
Various pages: Normalize NOTES about non-existing glibc wrappers
man2/add_key.2 | 5 +++--
man2/arch_prctl.2 | 9 +++++----
man2/clone.2 | 2 +-
man2/delete_module.2 | 2 +-
man2/getdents.2 | 8 ++++----
man2/init_module.2 | 6 +-----
man2/io_cancel.2 | 2 +-
man2/io_destroy.2 | 2 +-
man2/io_getevents.2 | 2 +-
man2/io_setup.2 | 2 +-
man2/io_submit.2 | 2 +-
man2/kexec_load.2 | 3 +--
man2/keyctl.2 | 5 +++--
man2/pidfd_getfd.2 | 5 ++++-
man2/pidfd_open.2 | 5 ++++-
man2/pidfd_send_signal.2 | 4 +++-
man2/request_key.2 | 5 +++--
man2/s390_guarded_storage.2 | 6 ++++--
man2/s390_pci_mmio_write.2 | 6 ++++--
man2/s390_runtime_instr.2 | 6 ++++--
man2/s390_sthyi.2 | 6 ++++--
man2/sysctl.2 | 3 +--
22 files changed, 55 insertions(+), 41 deletions(-)
base-commit: c55f66855eccfcd92b35fe7b13a326121f2ee0fd
--
2.29.2
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
2020-12-29 14:38 [PATCH 0/2] Normalize notes about missing glibc wrappers Alejandro Colomar
@ 2020-12-29 14:39 ` Alejandro Colomar
2020-12-29 14:49 ` Alejandro Colomar (man-pages)
2020-12-29 20:27 ` Michael Kerrisk (man-pages)
2020-12-29 14:39 ` [PATCH 2/2] Various pages: Normalize NOTES " Alejandro Colomar
2020-12-29 20:19 ` [PATCH 0/2] Normalize notes about missing " Michael Kerrisk (man-pages)
2 siblings, 2 replies; 21+ messages in thread
From: Alejandro Colomar @ 2020-12-29 14:39 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man, Alejandro Colomar
From: Ganimedes Colomar <gacoan.linux@gmail.com>
To easily distinguish documentation about glibc wrappers from
documentation about kernel syscalls, let's have a normalized
'Note' in the SYNOPSIS, and a further explanation in the page body
(NOTES in most of them), as already happened in many (but not all)
of the manual pages for syscalls without a wrapper. Furthermore,
let's normalize the messages, following membarrier.2 (because it's
already quite extended), so that it's easy to use grep to find
those pages.
To find these pages, we used:
$ grep -rn wrapper man? | sort -V
and
$ grep -rni support.*glibc | sort -V
delete_module.2, init_module.2: glibc 2.23 is no longer
maintained, so we changed the notes about wrappers, to say that
there are no glibc wrappers for these system calls; see NOTES.
We didn't fix some of the obsolete syscalls (create_module(2)),
but if you prefer, we can fix those too.
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
Hi Michael,
Some comment:
syslog.2: Isn't the comment in SYNOPSIS wrong?
There _is_ a wrapper, which is documented just below that line.
It just has a different name.
Cheers,
Alex
man2/add_key.2 | 3 ++-
man2/arch_prctl.2 | 3 +++
man2/clone.2 | 2 +-
man2/delete_module.2 | 2 +-
man2/init_module.2 | 6 +-----
man2/keyctl.2 | 3 ++-
man2/pidfd_getfd.2 | 3 +++
man2/pidfd_open.2 | 3 +++
man2/pidfd_send_signal.2 | 2 ++
man2/request_key.2 | 3 ++-
man2/s390_guarded_storage.2 | 3 +++
man2/s390_pci_mmio_write.2 | 3 +++
man2/s390_runtime_instr.2 | 3 +++
man2/s390_sthyi.2 | 3 +++
14 files changed, 32 insertions(+), 10 deletions(-)
diff --git a/man2/add_key.2 b/man2/add_key.2
index 1476b7d85..7c20de777 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility
.BI " key_serial_t " keyring ");"
.fi
.PP
-No glibc wrapper is provided for this system call; see NOTES.
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR add_key ()
creates or updates a key of the given
diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index 97d5a2fe5..e8a6da391 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state
.BI "int arch_prctl(int " code ", unsigned long " addr );
.BI "int arch_prctl(int " code ", unsigned long *" addr );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR arch_prctl ()
sets architecture-specific process or thread state.
diff --git a/man2/clone.2 b/man2/clone.2
index 0114668ea..0d6565b5d 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process
.fi
.PP
.IR Note :
-There is not yet a glibc wrapper for
+There is no glibc wrapper for
.BR clone3 ();
see NOTES.
.SH DESCRIPTION
diff --git a/man2/delete_module.2 b/man2/delete_module.2
index daa15faa2..e63545d51 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -31,7 +31,7 @@ delete_module \- unload a kernel module
.fi
.PP
.IR Note :
-No declaration of this system call is provided in glibc headers; see NOTES.
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR delete_module ()
diff --git a/man2/init_module.2 b/man2/init_module.2
index c2675db97..00cf4e948 100644
--- a/man2/init_module.2
+++ b/man2/init_module.2
@@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module
.fi
.PP
.IR Note :
-glibc provides no header file declaration of
-.BR init_module ()
-and no wrapper function for
-.BR finit_module ();
-see NOTES.
+There are no glibc wrappers for these system calls; see NOTES.
.SH DESCRIPTION
.BR init_module ()
loads an ELF image into kernel space,
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 6bf07972d..f37cae8df 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility
.BI " __kernel_ulong_t " arg5 );
.fi
.PP
-No glibc wrapper is provided for this system call; see NOTES.
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.
diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
index 1a69c8238..9312b6f92 100644
--- a/man2/pidfd_getfd.2
+++ b/man2/pidfd_getfd.2
@@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor
.nf
.BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR pidfd_getfd ()
diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
index 5b99460e1..1b0c5e0d4 100644
--- a/man2/pidfd_open.2
+++ b/man2/pidfd_open.2
@@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process
.PP
.BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR pidfd_open ()
diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
index 6670cf357..ffbfd1796 100644
--- a/man2/pidfd_send_signal.2
+++ b/man2/pidfd_send_signal.2
@@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor
.BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
.BI " unsigned int " flags );
.fi
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR pidfd_send_signal ()
diff --git a/man2/request_key.2 b/man2/request_key.2
index 86f76e43d..6b041d0c4 100644
--- a/man2/request_key.2
+++ b/man2/request_key.2
@@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility
.BI " key_serial_t " dest_keyring ");"
.fi
.PP
-No glibc wrapper is provided for this system call; see NOTES.
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR request_key ()
attempts to find a key of the given
diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
index b3aef858f..c3ab3bc85 100644
--- a/man2/s390_guarded_storage.2
+++ b/man2/s390_guarded_storage.2
@@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
.PP
.BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR s390_guarded_storage ()
diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
index 802142987..2ccd630ab 100644
--- a/man2/s390_pci_mmio_write.2
+++ b/man2/s390_pci_mmio_write.2
@@ -35,6 +35,9 @@ MMIO memory page
.BI "int s390_pci_mmio_read(unsigned long " mmio_addr ","
.BI " void *" user_buffer ", size_t " length ");"
.fi
+.PP
+.IR Note :
+There are no glibc wrappers for these system calls; see NOTES.
.SH DESCRIPTION
The
.BR s390_pci_mmio_write ()
diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 558e9c99d..0f4a704de 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
.PP
.BI "int s390_runtime_instr(int " command ", int " signum ");"
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR s390_runtime_instr ()
diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
index 2ff06051a..70871286b 100644
--- a/man2/s390_sthyi.2
+++ b/man2/s390_sthyi.2
@@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction
.BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ","
.BI " uint64_t *" return_code ", unsigned long " flags ");"
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR s390_sthyi ()
--
2.29.2
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
2020-12-29 14:38 [PATCH 0/2] Normalize notes about missing glibc wrappers Alejandro Colomar
2020-12-29 14:39 ` [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing " Alejandro Colomar
@ 2020-12-29 14:39 ` Alejandro Colomar
2020-12-29 20:32 ` Michael Kerrisk (man-pages)
2020-12-29 20:19 ` [PATCH 0/2] Normalize notes about missing " Michael Kerrisk (man-pages)
2 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar @ 2020-12-29 14:39 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man, Alejandro Colomar
From: Ganimedes Colomar <gacoan.linux@gmail.com>
See previous commit.
This commit normalizes texts under sections other than SYNOPSIS
(most of them in NOTES).
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
man2/add_key.2 | 2 +-
man2/arch_prctl.2 | 6 ++----
man2/getdents.2 | 8 ++++----
man2/io_cancel.2 | 2 +-
man2/io_destroy.2 | 2 +-
man2/io_getevents.2 | 2 +-
man2/io_setup.2 | 2 +-
man2/io_submit.2 | 2 +-
man2/kexec_load.2 | 3 +--
man2/keyctl.2 | 2 +-
man2/pidfd_getfd.2 | 2 +-
man2/pidfd_open.2 | 2 +-
man2/pidfd_send_signal.2 | 2 +-
man2/request_key.2 | 2 +-
man2/s390_guarded_storage.2 | 3 +--
man2/s390_pci_mmio_write.2 | 3 +--
man2/s390_runtime_instr.2 | 3 +--
man2/s390_sthyi.2 | 3 +--
man2/sysctl.2 | 3 +--
19 files changed, 23 insertions(+), 31 deletions(-)
diff --git a/man2/add_key.2 b/man2/add_key.2
index 7c20de777..0d136e4aa 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -216,7 +216,7 @@ This system call first appeared in Linux 2.6.10.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
-No wrapper for this system call is provided in glibc.
+Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
.IR libkeyutils
package.
diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index e8a6da391..f9a9dc39d 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -177,10 +177,8 @@ and
in the same thread is dangerous, as they may overwrite each other's
TLS entries.
.PP
-As of version 2.7, glibc provides no prototype for
-.BR arch_prctl ().
-You have to declare it yourself for now.
-This may be fixed in future glibc versions.
+Glibc does not provide a wrapper for this system call; call it using
+.BR syscall (2).
.PP
.I FS
may be already used by the threading library.
diff --git a/man2/getdents.2 b/man2/getdents.2
index 8fe6f90fc..2a0576ffd 100644
--- a/man2/getdents.2
+++ b/man2/getdents.2
@@ -211,13 +211,13 @@ SVr4.
Library support for
.BR getdents64 ()
was added in glibc 2.30;
-there is no glibc wrapper for
-.BR getdents ().
-Calling
+Glibc does not provide a wrapper for
+.BR getdents ();
+call
.BR getdents ()
(or
.BR getdents64 ()
-on earlier glibc versions) requires the use of
+on earlier glibc versions) using
.BR syscall (2).
In that case you will need to define the
.I linux_dirent
diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index 1bea257ec..8bcd9c195 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -68,7 +68,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used
in programs that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index dc9633f5a..89defd867 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -57,7 +57,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in programs
that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index c9a608e06..0f7c17dbf 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -94,7 +94,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in
programs that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index 5168ee445..e08d19bb8 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -72,7 +72,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in programs
that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_submit.2 b/man2/io_submit.2
index bcbcf43b9..6cdd018a5 100644
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -247,7 +247,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in
programs that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/kexec_load.2 b/man2/kexec_load.2
index a7114545a..4951eb5c3 100644
--- a/man2/kexec_load.2
+++ b/man2/kexec_load.2
@@ -335,8 +335,7 @@ system call first appeared in Linux 3.17.
.SH CONFORMING TO
These system calls are Linux-specific.
.SH NOTES
-Currently, there is no glibc support for these system calls.
-Call them using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.SH SEE ALSO
.BR reboot (2),
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index f37cae8df..9311100cf 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -1953,7 +1953,7 @@ This system call first appeared in Linux 2.6.10.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
-No wrapper for this system call is provided in glibc.
+Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
.IR libkeyutils
library.
diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
index 9312b6f92..1a1319aae 100644
--- a/man2/pidfd_getfd.2
+++ b/man2/pidfd_getfd.2
@@ -121,7 +121,7 @@ first appeared in Linux 5.6.
.BR pidfd_getfd ()
is Linux specific.
.SH NOTES
-Currently, there is no glibc wrapper for this system call; call it using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.PP
For a description of PID file descriptors, see
diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
index 1b0c5e0d4..b6a321562 100644
--- a/man2/pidfd_open.2
+++ b/man2/pidfd_open.2
@@ -91,7 +91,7 @@ first appeared in Linux 5.3.
.BR pidfd_open ()
is Linux specific.
.SH NOTES
-Currently, there is no glibc wrapper for this system call; call it using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.PP
The following code sequence can be used to obtain a file descriptor
diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
index ffbfd1796..7b1dc782d 100644
--- a/man2/pidfd_send_signal.2
+++ b/man2/pidfd_send_signal.2
@@ -135,7 +135,7 @@ first appeared in Linux 5.1.
.BR pidfd_send_signal ()
is Linux specific.
.SH NOTES
-Currently, there is no glibc wrapper for this system call; call it using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.\"
.SS PID file descriptors
diff --git a/man2/request_key.2 b/man2/request_key.2
index 6b041d0c4..997c221b7 100644
--- a/man2/request_key.2
+++ b/man2/request_key.2
@@ -439,7 +439,7 @@ in Linux 2.6.13.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
-No wrapper for this system call is provided in glibc.
+Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
.IR libkeyutils
package.
diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
index c3ab3bc85..c20230786 100644
--- a/man2/s390_guarded_storage.2
+++ b/man2/s390_guarded_storage.2
@@ -144,9 +144,8 @@ This Linux-specific system call is available only on the s390 architecture.
.PP
The guarded storage facility is available beginning with System z14.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2)
-to call it.
.PP
The description of the guarded storage facility along with related
instructions and Guarded Storage Control Block and
diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
index 2ccd630ab..5897c967e 100644
--- a/man2/s390_pci_mmio_write.2
+++ b/man2/s390_pci_mmio_write.2
@@ -103,8 +103,7 @@ These system calls are available since Linux 3.19.
This Linux-specific system call is available only on the s390 architecture.
The required PCI support is available beginning with System z EC12.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide wrappers for these system calls; call them using
.BR syscall (2)
-to call it.
.SH SEE ALSO
.BR syscall (2)
diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 0f4a704de..71e391fe9 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -97,9 +97,8 @@ This Linux-specific system call is available only on the s390 architecture.
The run-time instrumentation facility is available
beginning with System z EC12.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2)
-to call it.
.PP
The
.I asm/runtime_instr.h
diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
index 70871286b..91fc622bc 100644
--- a/man2/s390_sthyi.2
+++ b/man2/s390_sthyi.2
@@ -126,9 +126,8 @@ This system call is available since Linux 4.15.
.SH CONFORMING TO
This Linux-specific system call is available only on the s390 architecture.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2)
-to call it.
.PP
For details of the STHYI instruction, see
.UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm
diff --git a/man2/sysctl.2 b/man2/sysctl.2
index 72f0af6f3..0ed68df00 100644
--- a/man2/sysctl.2
+++ b/man2/sysctl.2
@@ -120,8 +120,7 @@ Note that on older kernels where this system call still exists,
it is available only if the kernel was configured with the
.B CONFIG_SYSCTL_SYSCALL
option.
-Furthermore,
-glibc does not provide a wrapper for this system call,
+Furthermore, glibc does not provide a wrapper for this system call,
necessitating the use of
.BR syscall (2).
.SH BUGS
--
2.29.2
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
2020-12-29 14:39 ` [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing " Alejandro Colomar
@ 2020-12-29 14:49 ` Alejandro Colomar (man-pages)
2020-12-29 20:27 ` Michael Kerrisk (man-pages)
1 sibling, 0 replies; 21+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-29 14:49 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man
Hi Michael,
a few comments below.
Cheers,
Alex
On 12/29/20 3:39 PM, Alejandro Colomar wrote:
> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>
> To easily distinguish documentation about glibc wrappers from
> documentation about kernel syscalls, let's have a normalized
> 'Note' in the SYNOPSIS, and a further explanation in the page body
> (NOTES in most of them), as already happened in many (but not all)
> of the manual pages for syscalls without a wrapper. Furthermore,
> let's normalize the messages, following membarrier.2 (because it's
> already quite extended), so that it's easy to use grep to find
> those pages.
>
> To find these pages, we used:
> $ grep -rn wrapper man? | sort -V
> and
> $ grep -rni support.*glibc | sort -V
>
> delete_module.2, init_module.2: glibc 2.23 is no longer
> maintained, so we changed the notes about wrappers, to say that
> there are no glibc wrappers for these system calls; see NOTES.
>
> We didn't fix some of the obsolete syscalls (create_module(2)),
> but if you prefer, we can fix those too.
That shouldn't be in the commit msg, but in the email :)
>
>
> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>
> Hi Michael,
>
> Some comment:
>
> syslog.2: Isn't the comment in SYNOPSIS wrong?
> There _is_ a wrapper, which is documented just below that line.
> It just has a different name.
Normally, syscalls that do have a wrapper but with a different name,
there's no note saying that there is no wrapper (see eventfd(2)).
Your thoughts?
>
> Cheers,
>
> Alex
>
> man2/add_key.2 | 3 ++-
> man2/arch_prctl.2 | 3 +++
> man2/clone.2 | 2 +-
> man2/delete_module.2 | 2 +-
> man2/init_module.2 | 6 +-----
> man2/keyctl.2 | 3 ++-
> man2/pidfd_getfd.2 | 3 +++
> man2/pidfd_open.2 | 3 +++
> man2/pidfd_send_signal.2 | 2 ++
> man2/request_key.2 | 3 ++-
> man2/s390_guarded_storage.2 | 3 +++
> man2/s390_pci_mmio_write.2 | 3 +++
> man2/s390_runtime_instr.2 | 3 +++
> man2/s390_sthyi.2 | 3 +++
> 14 files changed, 32 insertions(+), 10 deletions(-)
>
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 1476b7d85..7c20de777 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility
> .BI " key_serial_t " keyring ");"
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR add_key ()
> creates or updates a key of the given
> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
> index 97d5a2fe5..e8a6da391 100644
> --- a/man2/arch_prctl.2
> +++ b/man2/arch_prctl.2
> @@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state
> .BI "int arch_prctl(int " code ", unsigned long " addr );
> .BI "int arch_prctl(int " code ", unsigned long *" addr );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR arch_prctl ()
> sets architecture-specific process or thread state.
> diff --git a/man2/clone.2 b/man2/clone.2
> index 0114668ea..0d6565b5d 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process
> .fi
> .PP
> .IR Note :
> -There is not yet a glibc wrapper for
> +There is no glibc wrapper for
> .BR clone3 ();
> see NOTES.
> .SH DESCRIPTION
> diff --git a/man2/delete_module.2 b/man2/delete_module.2
> index daa15faa2..e63545d51 100644
> --- a/man2/delete_module.2
> +++ b/man2/delete_module.2
> @@ -31,7 +31,7 @@ delete_module \- unload a kernel module
> .fi
> .PP
> .IR Note :
> -No declaration of this system call is provided in glibc headers; see NOTES.
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR delete_module ()
> diff --git a/man2/init_module.2 b/man2/init_module.2
> index c2675db97..00cf4e948 100644
> --- a/man2/init_module.2
> +++ b/man2/init_module.2
> @@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module
> .fi
> .PP
> .IR Note :
> -glibc provides no header file declaration of
> -.BR init_module ()
> -and no wrapper function for
> -.BR finit_module ();
> -see NOTES.
> +There are no glibc wrappers for these system calls; see NOTES.
> .SH DESCRIPTION
> .BR init_module ()
> loads an ELF image into kernel space,
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index 6bf07972d..f37cae8df 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility
> .BI " __kernel_ulong_t " arg5 );
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR keyctl ()
> allows user-space programs to perform key manipulation.
> diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
> index 1a69c8238..9312b6f92 100644
> --- a/man2/pidfd_getfd.2
> +++ b/man2/pidfd_getfd.2
> @@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor
> .nf
> .BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_getfd ()
> diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
> index 5b99460e1..1b0c5e0d4 100644
> --- a/man2/pidfd_open.2
> +++ b/man2/pidfd_open.2
> @@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process
> .PP
> .BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_open ()
> diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
> index 6670cf357..ffbfd1796 100644
> --- a/man2/pidfd_send_signal.2
> +++ b/man2/pidfd_send_signal.2
> @@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor
> .BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
> .BI " unsigned int " flags );
> .fi
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_send_signal ()
> diff --git a/man2/request_key.2 b/man2/request_key.2
> index 86f76e43d..6b041d0c4 100644
> --- a/man2/request_key.2
> +++ b/man2/request_key.2
> @@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility
> .BI " key_serial_t " dest_keyring ");"
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR request_key ()
> attempts to find a key of the given
> diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
> index b3aef858f..c3ab3bc85 100644
> --- a/man2/s390_guarded_storage.2
> +++ b/man2/s390_guarded_storage.2
> @@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
> .PP
> .BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_guarded_storage ()
> diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
> index 802142987..2ccd630ab 100644
> --- a/man2/s390_pci_mmio_write.2
> +++ b/man2/s390_pci_mmio_write.2
> @@ -35,6 +35,9 @@ MMIO memory page
> .BI "int s390_pci_mmio_read(unsigned long " mmio_addr ","
> .BI " void *" user_buffer ", size_t " length ");"
> .fi
> +.PP
> +.IR Note :
> +There are no glibc wrappers for these system calls; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_pci_mmio_write ()
> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
> index 558e9c99d..0f4a704de 100644
> --- a/man2/s390_runtime_instr.2
> +++ b/man2/s390_runtime_instr.2
> @@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
> .PP
> .BI "int s390_runtime_instr(int " command ", int " signum ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_runtime_instr ()
> diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
> index 2ff06051a..70871286b 100644
> --- a/man2/s390_sthyi.2
> +++ b/man2/s390_sthyi.2
> @@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction
> .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ","
> .BI " uint64_t *" return_code ", unsigned long " flags ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_sthyi ()
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 0/2] Normalize notes about missing glibc wrappers
2020-12-29 14:38 [PATCH 0/2] Normalize notes about missing glibc wrappers Alejandro Colomar
2020-12-29 14:39 ` [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing " Alejandro Colomar
2020-12-29 14:39 ` [PATCH 2/2] Various pages: Normalize NOTES " Alejandro Colomar
@ 2020-12-29 20:19 ` Michael Kerrisk (man-pages)
2020-12-29 20:45 ` Alejandro Colomar (man-pages)
2 siblings, 1 reply; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-29 20:19 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man, Ganimedes Colomar
Hi Alex, hi Ganimedes!
On Tue, 29 Dec 2020 at 15:39, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> Here are 2 patches my brother and I prepared together.
Thanks. I'm really happy to have patches like this that bring
consistent language where exactly the same thing is being talked
about. I will send one or two comments on the patches.
> There are still some pages that we couldn't find with grep,
Does something like this help find others:
$ cd man2
$ grep -l syscall $(git grep -l wrapper)
?
Thanks,
Michael
> so I'll send you more patches continuing these 2 as I find them
> while fixing other things.
>
> Cheers,
>
> Alex
>
> Ganimedes Colomar (2):
> Various pages: Normalize SYNOPSIS notes about non-existing glibc
> wrappers
> Various pages: Normalize NOTES about non-existing glibc wrappers
>
> man2/add_key.2 | 5 +++--
> man2/arch_prctl.2 | 9 +++++----
> man2/clone.2 | 2 +-
> man2/delete_module.2 | 2 +-
> man2/getdents.2 | 8 ++++----
> man2/init_module.2 | 6 +-----
> man2/io_cancel.2 | 2 +-
> man2/io_destroy.2 | 2 +-
> man2/io_getevents.2 | 2 +-
> man2/io_setup.2 | 2 +-
> man2/io_submit.2 | 2 +-
> man2/kexec_load.2 | 3 +--
> man2/keyctl.2 | 5 +++--
> man2/pidfd_getfd.2 | 5 ++++-
> man2/pidfd_open.2 | 5 ++++-
> man2/pidfd_send_signal.2 | 4 +++-
> man2/request_key.2 | 5 +++--
> man2/s390_guarded_storage.2 | 6 ++++--
> man2/s390_pci_mmio_write.2 | 6 ++++--
> man2/s390_runtime_instr.2 | 6 ++++--
> man2/s390_sthyi.2 | 6 ++++--
> man2/sysctl.2 | 3 +--
> 22 files changed, 55 insertions(+), 41 deletions(-)
>
>
> base-commit: c55f66855eccfcd92b35fe7b13a326121f2ee0fd
> --
> 2.29.2
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
2020-12-29 14:39 ` [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing " Alejandro Colomar
2020-12-29 14:49 ` Alejandro Colomar (man-pages)
@ 2020-12-29 20:27 ` Michael Kerrisk (man-pages)
2020-12-29 20:51 ` Alejandro Colomar (man-pages)
1 sibling, 1 reply; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-29 20:27 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Ganimedes Colomar, linux-man
Hi Alex, Ganimedes.
In the subject line : s/non-existing/nonexistent/
On Tue, 29 Dec 2020 at 15:43, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>
> To easily distinguish documentation about glibc wrappers from
> documentation about kernel syscalls, let's have a normalized
> 'Note' in the SYNOPSIS, and a further explanation in the page body
> (NOTES in most of them), as already happened in many (but not all)
> of the manual pages for syscalls without a wrapper. Furthermore,
> let's normalize the messages, following membarrier.2 (because it's
> already quite extended), so that it's easy to use grep to find
> those pages.
>
> To find these pages, we used:
> $ grep -rn wrapper man? | sort -V
> and
> $ grep -rni support.*glibc | sort -V
>
> delete_module.2, init_module.2: glibc 2.23 is no longer
> maintained, so we changed the notes about wrappers, to say that
> there are no glibc wrappers for these system calls; see NOTES.
That seems fine.
> We didn't fix some of the obsolete syscalls (create_module(2)),
> but if you prefer, we can fix those too.
I think it's okay to leave it.
The remainder of the patch looks good. The only reason that I'm not
applying ir yet (and fixing the subject line myself) is that I wonder
if the command I mentioned in response to the 0/2 mail might help you
find other pages to include in the patch. Let me know.
Thanks,
Michael
>
>
> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>
> Hi Michael,
>
> Some comment:
>
> syslog.2: Isn't the comment in SYNOPSIS wrong?
> There _is_ a wrapper, which is documented just below that line.
> It just has a different name.
>
> Cheers,
>
> Alex
>
> man2/add_key.2 | 3 ++-
> man2/arch_prctl.2 | 3 +++
> man2/clone.2 | 2 +-
> man2/delete_module.2 | 2 +-
> man2/init_module.2 | 6 +-----
> man2/keyctl.2 | 3 ++-
> man2/pidfd_getfd.2 | 3 +++
> man2/pidfd_open.2 | 3 +++
> man2/pidfd_send_signal.2 | 2 ++
> man2/request_key.2 | 3 ++-
> man2/s390_guarded_storage.2 | 3 +++
> man2/s390_pci_mmio_write.2 | 3 +++
> man2/s390_runtime_instr.2 | 3 +++
> man2/s390_sthyi.2 | 3 +++
> 14 files changed, 32 insertions(+), 10 deletions(-)
>
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 1476b7d85..7c20de777 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility
> .BI " key_serial_t " keyring ");"
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR add_key ()
> creates or updates a key of the given
> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
> index 97d5a2fe5..e8a6da391 100644
> --- a/man2/arch_prctl.2
> +++ b/man2/arch_prctl.2
> @@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state
> .BI "int arch_prctl(int " code ", unsigned long " addr );
> .BI "int arch_prctl(int " code ", unsigned long *" addr );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR arch_prctl ()
> sets architecture-specific process or thread state.
> diff --git a/man2/clone.2 b/man2/clone.2
> index 0114668ea..0d6565b5d 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process
> .fi
> .PP
> .IR Note :
> -There is not yet a glibc wrapper for
> +There is no glibc wrapper for
> .BR clone3 ();
> see NOTES.
> .SH DESCRIPTION
> diff --git a/man2/delete_module.2 b/man2/delete_module.2
> index daa15faa2..e63545d51 100644
> --- a/man2/delete_module.2
> +++ b/man2/delete_module.2
> @@ -31,7 +31,7 @@ delete_module \- unload a kernel module
> .fi
> .PP
> .IR Note :
> -No declaration of this system call is provided in glibc headers; see NOTES.
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR delete_module ()
> diff --git a/man2/init_module.2 b/man2/init_module.2
> index c2675db97..00cf4e948 100644
> --- a/man2/init_module.2
> +++ b/man2/init_module.2
> @@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module
> .fi
> .PP
> .IR Note :
> -glibc provides no header file declaration of
> -.BR init_module ()
> -and no wrapper function for
> -.BR finit_module ();
> -see NOTES.
> +There are no glibc wrappers for these system calls; see NOTES.
> .SH DESCRIPTION
> .BR init_module ()
> loads an ELF image into kernel space,
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index 6bf07972d..f37cae8df 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility
> .BI " __kernel_ulong_t " arg5 );
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR keyctl ()
> allows user-space programs to perform key manipulation.
> diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
> index 1a69c8238..9312b6f92 100644
> --- a/man2/pidfd_getfd.2
> +++ b/man2/pidfd_getfd.2
> @@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor
> .nf
> .BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_getfd ()
> diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
> index 5b99460e1..1b0c5e0d4 100644
> --- a/man2/pidfd_open.2
> +++ b/man2/pidfd_open.2
> @@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process
> .PP
> .BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_open ()
> diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
> index 6670cf357..ffbfd1796 100644
> --- a/man2/pidfd_send_signal.2
> +++ b/man2/pidfd_send_signal.2
> @@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor
> .BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
> .BI " unsigned int " flags );
> .fi
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_send_signal ()
> diff --git a/man2/request_key.2 b/man2/request_key.2
> index 86f76e43d..6b041d0c4 100644
> --- a/man2/request_key.2
> +++ b/man2/request_key.2
> @@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility
> .BI " key_serial_t " dest_keyring ");"
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR request_key ()
> attempts to find a key of the given
> diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
> index b3aef858f..c3ab3bc85 100644
> --- a/man2/s390_guarded_storage.2
> +++ b/man2/s390_guarded_storage.2
> @@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
> .PP
> .BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_guarded_storage ()
> diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
> index 802142987..2ccd630ab 100644
> --- a/man2/s390_pci_mmio_write.2
> +++ b/man2/s390_pci_mmio_write.2
> @@ -35,6 +35,9 @@ MMIO memory page
> .BI "int s390_pci_mmio_read(unsigned long " mmio_addr ","
> .BI " void *" user_buffer ", size_t " length ");"
> .fi
> +.PP
> +.IR Note :
> +There are no glibc wrappers for these system calls; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_pci_mmio_write ()
> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
> index 558e9c99d..0f4a704de 100644
> --- a/man2/s390_runtime_instr.2
> +++ b/man2/s390_runtime_instr.2
> @@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
> .PP
> .BI "int s390_runtime_instr(int " command ", int " signum ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_runtime_instr ()
> diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
> index 2ff06051a..70871286b 100644
> --- a/man2/s390_sthyi.2
> +++ b/man2/s390_sthyi.2
> @@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction
> .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ","
> .BI " uint64_t *" return_code ", unsigned long " flags ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_sthyi ()
> --
> 2.29.2
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
2020-12-29 14:39 ` [PATCH 2/2] Various pages: Normalize NOTES " Alejandro Colomar
@ 2020-12-29 20:32 ` Michael Kerrisk (man-pages)
2020-12-29 20:53 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-29 20:32 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Ganimedes Colomar, linux-man
Hi Alex, Ganimedes,
Again, in the subject line, s/
non-existing/nonexistent/
[...]
> --- a/man2/getdents.2
> +++ b/man2/getdents.2
> @@ -211,13 +211,13 @@ SVr4.
> Library support for
> .BR getdents64 ()
> was added in glibc 2.30;
> -there is no glibc wrapper for
> -.BR getdents ().
> -Calling
> +Glibc does not provide a wrapper for
> +.BR getdents ();
> +call
s/call/calling/
> .BR getdents ()
> (or
> .BR getdents64 ()
> -on earlier glibc versions) requires the use of
> +on earlier glibc versions) using
> .BR syscall (2).
> In that case you will need to define the
> .I linux_dirent
[...]
Again, the only reason I'm not making these patches and making the
minor fixes is in case you find some other pages that might be added
to the patch. Let me know.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 0/2] Normalize notes about missing glibc wrappers
2020-12-29 20:19 ` [PATCH 0/2] Normalize notes about missing " Michael Kerrisk (man-pages)
@ 2020-12-29 20:45 ` Alejandro Colomar (man-pages)
2020-12-30 9:30 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-29 20:45 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, Ganimedes Colomar
On 12/29/20 9:19 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex, hi Ganimedes!
>
> On Tue, 29 Dec 2020 at 15:39, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>
>> Hi Michael,
>>
>> Here are 2 patches my brother and I prepared together.
>
> Thanks. I'm really happy to have patches like this that bring
> consistent language where exactly the same thing is being talked
> about. I will send one or two comments on the patches.
>
>> There are still some pages that we couldn't find with grep,
>
> Does something like this help find others:
>
> $ cd man2
> $ grep -l syscall $(git grep -l wrapper)
Hey M,
It may still not find everything, and I'll probably have to read through
a lot of text, so what I was doing is I'm comparing all the prototypes
against the glibc sources to fix them (I have a few of those patches
that I'm about to send (including the off64_t one).), and that way I'll
also find quickly which ones are missing in glibc.
Thanks,
Alex
>
> ?
>
> Thanks,
>
> Michael
>
>> so I'll send you more patches continuing these 2 as I find them
>> while fixing other things.
>>
>> Cheers,
>>
>> Alex
>>
>> Ganimedes Colomar (2):
>> Various pages: Normalize SYNOPSIS notes about non-existing glibc
>> wrappers
>> Various pages: Normalize NOTES about non-existing glibc wrappers
>>
>> man2/add_key.2 | 5 +++--
>> man2/arch_prctl.2 | 9 +++++----
>> man2/clone.2 | 2 +-
>> man2/delete_module.2 | 2 +-
>> man2/getdents.2 | 8 ++++----
>> man2/init_module.2 | 6 +-----
>> man2/io_cancel.2 | 2 +-
>> man2/io_destroy.2 | 2 +-
>> man2/io_getevents.2 | 2 +-
>> man2/io_setup.2 | 2 +-
>> man2/io_submit.2 | 2 +-
>> man2/kexec_load.2 | 3 +--
>> man2/keyctl.2 | 5 +++--
>> man2/pidfd_getfd.2 | 5 ++++-
>> man2/pidfd_open.2 | 5 ++++-
>> man2/pidfd_send_signal.2 | 4 +++-
>> man2/request_key.2 | 5 +++--
>> man2/s390_guarded_storage.2 | 6 ++++--
>> man2/s390_pci_mmio_write.2 | 6 ++++--
>> man2/s390_runtime_instr.2 | 6 ++++--
>> man2/s390_sthyi.2 | 6 ++++--
>> man2/sysctl.2 | 3 +--
>> 22 files changed, 55 insertions(+), 41 deletions(-)
>>
>>
>> base-commit: c55f66855eccfcd92b35fe7b13a326121f2ee0fd
>> --
>> 2.29.2
>>
>
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
2020-12-29 20:27 ` Michael Kerrisk (man-pages)
@ 2020-12-29 20:51 ` Alejandro Colomar (man-pages)
2020-12-30 9:37 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-29 20:51 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man
Hello Michael,
A question below.
Cheers,
Alex
On 12/29/20 9:27 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex, Ganimedes.
>
> In the subject line : s/non-existing/nonexistent/
Ok, I'll resend in a few minutes.
>
> On Tue, 29 Dec 2020 at 15:43, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>
>> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>>
>> To easily distinguish documentation about glibc wrappers from
>> documentation about kernel syscalls, let's have a normalized
>> 'Note' in the SYNOPSIS, and a further explanation in the page body
>> (NOTES in most of them), as already happened in many (but not all)
>> of the manual pages for syscalls without a wrapper. Furthermore,
>> let's normalize the messages, following membarrier.2 (because it's
>> already quite extended), so that it's easy to use grep to find
>> those pages.
>>
>> To find these pages, we used:
>> $ grep -rn wrapper man? | sort -V
>> and
>> $ grep -rni support.*glibc | sort -V
>>
>> delete_module.2, init_module.2: glibc 2.23 is no longer
>> maintained, so we changed the notes about wrappers, to say that
>> there are no glibc wrappers for these system calls; see NOTES.
>
> That seems fine.
>
>> We didn't fix some of the obsolete syscalls (create_module(2)),
>> but if you prefer, we can fix those too.
>
> I think it's okay to leave it.
>
> The remainder of the patch looks good. The only reason that I'm not
> applying ir yet (and fixing the subject line myself) is that I wonder
> if the command I mentioned in response to the 0/2 mail might help you
> find other pages to include in the patch. Let me know.
>
> Thanks,
>
> Michael
>
>
>
>>
>>
>> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
>> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>>
>> Hi Michael,
>>
>> Some comment:
>>
>> syslog.2: Isn't the comment in SYNOPSIS wrong?
>> There _is_ a wrapper, which is documented just below that line.
>> It just has a different name.
What about that?
$ man 2 syslog | sed -n /^SYNOPSIS/,/^DESCRIPTION/p |sed \$d
SYNOPSIS
int syslog(int type, char *bufp, int len);
/* No wrapper provided in glibc */
<<<<< I think we should remove the above comment,
<<<<< or put it consistently everywhere else.
<<<<< What would you do?
/* The glibc interface */
#include <sys/klog.h>
int klogctl(int type, char *bufp, int len);
>>
>> Cheers,
>>
>> Alex
>>
>> man2/add_key.2 | 3 ++-
>> man2/arch_prctl.2 | 3 +++
>> man2/clone.2 | 2 +-
>> man2/delete_module.2 | 2 +-
>> man2/init_module.2 | 6 +-----
>> man2/keyctl.2 | 3 ++-
>> man2/pidfd_getfd.2 | 3 +++
>> man2/pidfd_open.2 | 3 +++
>> man2/pidfd_send_signal.2 | 2 ++
>> man2/request_key.2 | 3 ++-
>> man2/s390_guarded_storage.2 | 3 +++
>> man2/s390_pci_mmio_write.2 | 3 +++
>> man2/s390_runtime_instr.2 | 3 +++
>> man2/s390_sthyi.2 | 3 +++
>> 14 files changed, 32 insertions(+), 10 deletions(-)
>>
>> diff --git a/man2/add_key.2 b/man2/add_key.2
>> index 1476b7d85..7c20de777 100644
>> --- a/man2/add_key.2
>> +++ b/man2/add_key.2
>> @@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility
>> .BI " key_serial_t " keyring ");"
>> .fi
>> .PP
>> -No glibc wrapper is provided for this system call; see NOTES.
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> .BR add_key ()
>> creates or updates a key of the given
>> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
>> index 97d5a2fe5..e8a6da391 100644
>> --- a/man2/arch_prctl.2
>> +++ b/man2/arch_prctl.2
>> @@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state
>> .BI "int arch_prctl(int " code ", unsigned long " addr );
>> .BI "int arch_prctl(int " code ", unsigned long *" addr );
>> .fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> .BR arch_prctl ()
>> sets architecture-specific process or thread state.
>> diff --git a/man2/clone.2 b/man2/clone.2
>> index 0114668ea..0d6565b5d 100644
>> --- a/man2/clone.2
>> +++ b/man2/clone.2
>> @@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process
>> .fi
>> .PP
>> .IR Note :
>> -There is not yet a glibc wrapper for
>> +There is no glibc wrapper for
>> .BR clone3 ();
>> see NOTES.
>> .SH DESCRIPTION
>> diff --git a/man2/delete_module.2 b/man2/delete_module.2
>> index daa15faa2..e63545d51 100644
>> --- a/man2/delete_module.2
>> +++ b/man2/delete_module.2
>> @@ -31,7 +31,7 @@ delete_module \- unload a kernel module
>> .fi
>> .PP
>> .IR Note :
>> -No declaration of this system call is provided in glibc headers; see NOTES.
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR delete_module ()
>> diff --git a/man2/init_module.2 b/man2/init_module.2
>> index c2675db97..00cf4e948 100644
>> --- a/man2/init_module.2
>> +++ b/man2/init_module.2
>> @@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module
>> .fi
>> .PP
>> .IR Note :
>> -glibc provides no header file declaration of
>> -.BR init_module ()
>> -and no wrapper function for
>> -.BR finit_module ();
>> -see NOTES.
>> +There are no glibc wrappers for these system calls; see NOTES.
>> .SH DESCRIPTION
>> .BR init_module ()
>> loads an ELF image into kernel space,
>> diff --git a/man2/keyctl.2 b/man2/keyctl.2
>> index 6bf07972d..f37cae8df 100644
>> --- a/man2/keyctl.2
>> +++ b/man2/keyctl.2
>> @@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility
>> .BI " __kernel_ulong_t " arg5 );
>> .fi
>> .PP
>> -No glibc wrapper is provided for this system call; see NOTES.
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> .BR keyctl ()
>> allows user-space programs to perform key manipulation.
>> diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
>> index 1a69c8238..9312b6f92 100644
>> --- a/man2/pidfd_getfd.2
>> +++ b/man2/pidfd_getfd.2
>> @@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor
>> .nf
>> .BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
>> .fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR pidfd_getfd ()
>> diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
>> index 5b99460e1..1b0c5e0d4 100644
>> --- a/man2/pidfd_open.2
>> +++ b/man2/pidfd_open.2
>> @@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process
>> .PP
>> .BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
>> .fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR pidfd_open ()
>> diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
>> index 6670cf357..ffbfd1796 100644
>> --- a/man2/pidfd_send_signal.2
>> +++ b/man2/pidfd_send_signal.2
>> @@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor
>> .BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
>> .BI " unsigned int " flags );
>> .fi
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR pidfd_send_signal ()
>> diff --git a/man2/request_key.2 b/man2/request_key.2
>> index 86f76e43d..6b041d0c4 100644
>> --- a/man2/request_key.2
>> +++ b/man2/request_key.2
>> @@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility
>> .BI " key_serial_t " dest_keyring ");"
>> .fi
>> .PP
>> -No glibc wrapper is provided for this system call; see NOTES.
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> .BR request_key ()
>> attempts to find a key of the given
>> diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
>> index b3aef858f..c3ab3bc85 100644
>> --- a/man2/s390_guarded_storage.2
>> +++ b/man2/s390_guarded_storage.2
>> @@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
>> .PP
>> .BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
>> .fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR s390_guarded_storage ()
>> diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
>> index 802142987..2ccd630ab 100644
>> --- a/man2/s390_pci_mmio_write.2
>> +++ b/man2/s390_pci_mmio_write.2
>> @@ -35,6 +35,9 @@ MMIO memory page
>> .BI "int s390_pci_mmio_read(unsigned long " mmio_addr ","
>> .BI " void *" user_buffer ", size_t " length ");"
>> .fi
>> +.PP
>> +.IR Note :
>> +There are no glibc wrappers for these system calls; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR s390_pci_mmio_write ()
>> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
>> index 558e9c99d..0f4a704de 100644
>> --- a/man2/s390_runtime_instr.2
>> +++ b/man2/s390_runtime_instr.2
>> @@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
>> .PP
>> .BI "int s390_runtime_instr(int " command ", int " signum ");"
>> .fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR s390_runtime_instr ()
>> diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
>> index 2ff06051a..70871286b 100644
>> --- a/man2/s390_sthyi.2
>> +++ b/man2/s390_sthyi.2
>> @@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction
>> .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ","
>> .BI " uint64_t *" return_code ", unsigned long " flags ");"
>> .fi
>> +.PP
>> +.IR Note :
>> +There is no glibc wrapper for this system call; see NOTES.
>> .SH DESCRIPTION
>> The
>> .BR s390_sthyi ()
>> --
>> 2.29.2
>>
>
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
2020-12-29 20:32 ` Michael Kerrisk (man-pages)
@ 2020-12-29 20:53 ` Alejandro Colomar (man-pages)
2020-12-30 9:38 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-29 20:53 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man
Hi Michael,
Please, see a comment below.
Thanks,
Alex
On 12/29/20 9:32 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex, Ganimedes,
>
> Again, in the subject line, s/
>
> non-existing/nonexistent/
>
> [...]
>
>> --- a/man2/getdents.2
>> +++ b/man2/getdents.2
>> @@ -211,13 +211,13 @@ SVr4.
>> Library support for
>> .BR getdents64 ()
>> was added in glibc 2.30;
>> -there is no glibc wrapper for
>> -.BR getdents ().
>> -Calling
>> +Glibc does not provide a wrapper for
>> +.BR getdents ();
>> +call
>
> s/call/calling/
See below
>
>> .BR getdents ()
>> (or
>> .BR getdents64 ()
>> -on earlier glibc versions) requires the use of
>> +on earlier glibc versions) using
The new version is 'Call XXX using syscall(2).'.
>> .BR syscall (2).
>> In that case you will need to define the
>> .I linux_dirent
>
> [...]
>
> Again, the only reason I'm not making these patches and making the
> minor fixes is in case you find some other pages that might be added
> to the patch. Let me know.
>
> Thanks,
>
> Michael
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 0/2] Normalize notes about missing glibc wrappers
2020-12-29 20:45 ` Alejandro Colomar (man-pages)
@ 2020-12-30 9:30 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-30 9:30 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: linux-man, Ganimedes Colomar
Hi Alex,
On Tue, 29 Dec 2020 at 21:45, Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
>
>
> On 12/29/20 9:19 PM, Michael Kerrisk (man-pages) wrote:
> > Hi Alex, hi Ganimedes!
> >
> > On Tue, 29 Dec 2020 at 15:39, Alejandro Colomar <alx.manpages@gmail.com> wrote:
> >>
> >> Hi Michael,
> >>
> >> Here are 2 patches my brother and I prepared together.
> >
> > Thanks. I'm really happy to have patches like this that bring
> > consistent language where exactly the same thing is being talked
> > about. I will send one or two comments on the patches.
> >
> >> There are still some pages that we couldn't find with grep,
> >
> > Does something like this help find others:
> >
> > $ cd man2
> > $ grep -l syscall $(git grep -l wrapper)
>
> Hey M,
>
> It may still not find everything, and I'll probably have to read through
> a lot of text, so what I was doing is I'm comparing all the prototypes
> against the glibc sources to fix them (I have a few of those patches
> that I'm about to send (including the off64_t one).), and that way I'll
> also find quickly which ones are missing in glibc.
Okay. From an off-list mail I recently received, I note also that
seccomp(2) is missing a statement that the use of syscall() is
required.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
2020-12-29 20:51 ` Alejandro Colomar (man-pages)
@ 2020-12-30 9:37 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-30 9:37 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: Ganimedes Colomar, linux-man
Hi Alex,
On Tue, 29 Dec 2020 at 21:51, Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hello Michael,
>
> A question below.
>
> Cheers,
>
> Alex
>
> On 12/29/20 9:27 PM, Michael Kerrisk (man-pages) wrote:
> > Hi Alex, Ganimedes.
> >
> > In the subject line : s/non-existing/nonexistent/
>
> Ok, I'll resend in a few minutes.
>
> >
> > On Tue, 29 Dec 2020 at 15:43, Alejandro Colomar <alx.manpages@gmail.com> wrote:
> >>
> >> From: Ganimedes Colomar <gacoan.linux@gmail.com>
> >>
> >> To easily distinguish documentation about glibc wrappers from
> >> documentation about kernel syscalls, let's have a normalized
> >> 'Note' in the SYNOPSIS, and a further explanation in the page body
> >> (NOTES in most of them), as already happened in many (but not all)
> >> of the manual pages for syscalls without a wrapper. Furthermore,
> >> let's normalize the messages, following membarrier.2 (because it's
> >> already quite extended), so that it's easy to use grep to find
> >> those pages.
> >>
> >> To find these pages, we used:
> >> $ grep -rn wrapper man? | sort -V
> >> and
> >> $ grep -rni support.*glibc | sort -V
> >>
> >> delete_module.2, init_module.2: glibc 2.23 is no longer
> >> maintained, so we changed the notes about wrappers, to say that
> >> there are no glibc wrappers for these system calls; see NOTES.
> >
> > That seems fine.
> >
> >> We didn't fix some of the obsolete syscalls (create_module(2)),
> >> but if you prefer, we can fix those too.
> >
> > I think it's okay to leave it.
> >
> > The remainder of the patch looks good. The only reason that I'm not
> > applying ir yet (and fixing the subject line myself) is that I wonder
> > if the command I mentioned in response to the 0/2 mail might help you
> > find other pages to include in the patch. Let me know.
> >
> > Thanks,
> >
> > Michael
> >
> >
> >
> >>
> >>
> >> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
> >> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> >> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> >> ---
> >>
> >> Hi Michael,
> >>
> >> Some comment:
> >>
> >> syslog.2: Isn't the comment in SYNOPSIS wrong?
> >> There _is_ a wrapper, which is documented just below that line.
> >> It just has a different name.
>
> What about that?
>
> $ man 2 syslog | sed -n /^SYNOPSIS/,/^DESCRIPTION/p |sed \$d
> SYNOPSIS
> int syslog(int type, char *bufp, int len);
> /* No wrapper provided in glibc */
> <<<<< I think we should remove the above comment,
> <<<<< or put it consistently everywhere else.
> <<<<< What would you do?
Yep, remove the comment.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
2020-12-29 20:53 ` Alejandro Colomar (man-pages)
@ 2020-12-30 9:38 ` Michael Kerrisk (man-pages)
2020-12-30 12:52 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-30 9:38 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: Ganimedes Colomar, linux-man
Hi Alex,
On Tue, 29 Dec 2020 at 21:53, Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> Please, see a comment below.
>
> Thanks,
>
> Alex
>
> On 12/29/20 9:32 PM, Michael Kerrisk (man-pages) wrote:
> > Hi Alex, Ganimedes,
> >
> > Again, in the subject line, s/
> >
> > non-existing/nonexistent/
> >
> > [...]
> >
> >> --- a/man2/getdents.2
> >> +++ b/man2/getdents.2
> >> @@ -211,13 +211,13 @@ SVr4.
> >> Library support for
> >> .BR getdents64 ()
> >> was added in glibc 2.30;
> >> -there is no glibc wrapper for
> >> -.BR getdents ().
> >> -Calling
> >> +Glibc does not provide a wrapper for
> >> +.BR getdents ();
> >> +call
> >
> > s/call/calling/
>
> See below
>
> >
> >> .BR getdents ()
> >> (or
> >> .BR getdents64 ()
> >> -on earlier glibc versions) requires the use of
> >> +on earlier glibc versions) using
>
> The new version is 'Call XXX using syscall(2).'.
I need more context here please. What do you mean with "The new version"?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
2020-12-30 9:38 ` Michael Kerrisk (man-pages)
@ 2020-12-30 12:52 ` Alejandro Colomar (man-pages)
2020-12-30 13:23 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-30 12:52 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man
On 12/30/20 10:38 AM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On Tue, 29 Dec 2020 at 21:53, Alejandro Colomar (man-pages)
> <alx.manpages@gmail.com> wrote:
>>
>> Hi Michael,
>>
>> Please, see a comment below.
>>
>> Thanks,
>>
>> Alex
>>
>> On 12/29/20 9:32 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex, Ganimedes,
>>>
>>> Again, in the subject line, s/
>>>
>>> non-existing/nonexistent/
>>>
>>> [...]
>>>
>>>> --- a/man2/getdents.2
>>>> +++ b/man2/getdents.2
>>>> @@ -211,13 +211,13 @@ SVr4.
>>>> Library support for
>>>> .BR getdents64 ()
>>>> was added in glibc 2.30;
>>>> -there is no glibc wrapper for
>>>> -.BR getdents ().
>>>> -Calling
>>>> +Glibc does not provide a wrapper for
>>>> +.BR getdents ();
>>>> +call
>>>
>>> s/call/calling/
>>
>> See below
>>
>>>
>>>> .BR getdents ()
>>>> (or
>>>> .BR getdents64 ()
>>>> -on earlier glibc versions) requires the use of
>>>> +on earlier glibc versions) using
>>
>> The new version is 'Call XXX using syscall(2).'.
>
> I need more context here please. What do you mean with "The new version"?
Hi Michael,
I mean after applying this patch.
This patch changes ". Calling XXX requires the use of syscall(2)"
to "; call XXX using syscall(2)".
"; calling XXX using syscall(2)" wouldn't make sense.
Thanks,
Alex
>
> Thanks,
>
> Michael
>
>
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
2020-12-30 12:52 ` Alejandro Colomar (man-pages)
@ 2020-12-30 13:23 ` Michael Kerrisk (man-pages)
2020-12-30 15:20 ` [PATCH v2 0/2] Normalize notes about missing " Alejandro Colomar
` (2 more replies)
0 siblings, 3 replies; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-30 13:23 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: mtk.manpages, Ganimedes Colomar, linux-man
On 12/30/20 1:52 PM, Alejandro Colomar (man-pages) wrote:
>
>
> On 12/30/20 10:38 AM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On Tue, 29 Dec 2020 at 21:53, Alejandro Colomar (man-pages)
>> <alx.manpages@gmail.com> wrote:
>>>
>>> Hi Michael,
>>>
>>> Please, see a comment below.
>>>
>>> Thanks,
>>>
>>> Alex
>>>
>>> On 12/29/20 9:32 PM, Michael Kerrisk (man-pages) wrote:
>>>> Hi Alex, Ganimedes,
>>>>
>>>> Again, in the subject line, s/
>>>>
>>>> non-existing/nonexistent/
>>>>
>>>> [...]
>>>>
>>>>> --- a/man2/getdents.2
>>>>> +++ b/man2/getdents.2
>>>>> @@ -211,13 +211,13 @@ SVr4.
>>>>> Library support for
>>>>> .BR getdents64 ()
>>>>> was added in glibc 2.30;
>>>>> -there is no glibc wrapper for
>>>>> -.BR getdents ().
>>>>> -Calling
>>>>> +Glibc does not provide a wrapper for
>>>>> +.BR getdents ();
>>>>> +call
>>>>
>>>> s/call/calling/
>>>
>>> See below
>>>
>>>>
>>>>> .BR getdents ()
>>>>> (or
>>>>> .BR getdents64 ()
>>>>> -on earlier glibc versions) requires the use of
>>>>> +on earlier glibc versions) using
>>>
>>> The new version is 'Call XXX using syscall(2).'.
>>
>> I need more context here please. What do you mean with "The new version"?
>
> Hi Michael,
>
> I mean after applying this patch.
>
> This patch changes ". Calling XXX requires the use of syscall(2)"
> to "; call XXX using syscall(2)".
>
> "; calling XXX using syscall(2)" wouldn't make sense.
Sorry -- got it now. I misread the patch.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 0/2] Normalize notes about missing glibc wrappers
2020-12-30 13:23 ` Michael Kerrisk (man-pages)
@ 2020-12-30 15:20 ` Alejandro Colomar
2020-12-30 15:20 ` [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent " Alejandro Colomar
2020-12-30 15:20 ` [PATCH v2 2/2] Various pages: Normalize NOTES " Alejandro Colomar
2 siblings, 0 replies; 21+ messages in thread
From: Alejandro Colomar @ 2020-12-30 15:20 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, Alejandro Colomar, linux-man
* v2:
s/non-existing/nonexistent/
Fix seccomp.2, syslog.2, and some other pages.
Ganimedes Colomar (2):
Various pages: Normalize SYNOPSIS notes about nonexistent glibc
wrappers
Various pages: Normalize NOTES about nonexistent glibc wrappers
man2/add_key.2 | 5 +++--
man2/arch_prctl.2 | 9 +++++----
man2/clone.2 | 2 +-
man2/delete_module.2 | 2 +-
man2/getdents.2 | 8 ++++----
man2/init_module.2 | 6 +-----
man2/io_cancel.2 | 2 +-
man2/io_destroy.2 | 2 +-
man2/io_getevents.2 | 2 +-
man2/io_setup.2 | 2 +-
man2/io_submit.2 | 2 +-
man2/kexec_load.2 | 3 +--
man2/keyctl.2 | 5 +++--
man2/pidfd_getfd.2 | 5 ++++-
man2/pidfd_open.2 | 5 ++++-
man2/pidfd_send_signal.2 | 4 +++-
man2/request_key.2 | 5 +++--
man2/s390_guarded_storage.2 | 6 ++++--
man2/s390_pci_mmio_write.2 | 6 ++++--
man2/s390_runtime_instr.2 | 6 ++++--
man2/s390_sthyi.2 | 6 ++++--
man2/seccomp.2 | 6 ++++++
man2/sysctl.2 | 3 +--
man2/syslog.2 | 1 -
24 files changed, 61 insertions(+), 42 deletions(-)
--
2.29.2
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent glibc wrappers
2020-12-30 13:23 ` Michael Kerrisk (man-pages)
2020-12-30 15:20 ` [PATCH v2 0/2] Normalize notes about missing " Alejandro Colomar
@ 2020-12-30 15:20 ` Alejandro Colomar
2020-12-30 19:20 ` Michael Kerrisk (man-pages)
2020-12-30 15:20 ` [PATCH v2 2/2] Various pages: Normalize NOTES " Alejandro Colomar
2 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar @ 2020-12-30 15:20 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man, Alejandro Colomar
From: Ganimedes Colomar <gacoan.linux@gmail.com>
To easily distinguish documentation about glibc wrappers from
documentation about kernel syscalls, let's have a normalized
'Note' in the SYNOPSIS, and a further explanation in the page body
(NOTES in most of them), as already happened in many (but not all)
of the manual pages for syscalls without a wrapper. Furthermore,
let's normalize the messages, following membarrier.2 (because it's
already quite extended), so that it's easy to use grep to find
those pages.
To find these pages, we used:
$ grep -rn wrapper man? | sort -V
and
$ grep -rni support.*glibc | sort -V
delete_module.2, init_module.2: glibc 2.23 is no longer
maintained, so we changed the notes about wrappers, to say that
there are no glibc wrappers for these system calls; see NOTES.
We didn't fix some obsolete pages such as create_module.2.
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
man2/add_key.2 | 3 ++-
man2/arch_prctl.2 | 3 +++
man2/clone.2 | 2 +-
man2/delete_module.2 | 2 +-
man2/init_module.2 | 6 +-----
man2/keyctl.2 | 3 ++-
man2/pidfd_getfd.2 | 3 +++
man2/pidfd_open.2 | 3 +++
man2/pidfd_send_signal.2 | 2 ++
man2/request_key.2 | 3 ++-
man2/s390_guarded_storage.2 | 3 +++
man2/s390_pci_mmio_write.2 | 3 +++
man2/s390_runtime_instr.2 | 3 +++
man2/s390_sthyi.2 | 3 +++
man2/seccomp.2 | 3 +++
man2/syslog.2 | 1 -
16 files changed, 35 insertions(+), 11 deletions(-)
diff --git a/man2/add_key.2 b/man2/add_key.2
index 1476b7d85..7c20de777 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility
.BI " key_serial_t " keyring ");"
.fi
.PP
-No glibc wrapper is provided for this system call; see NOTES.
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR add_key ()
creates or updates a key of the given
diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index 97d5a2fe5..e8a6da391 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state
.BI "int arch_prctl(int " code ", unsigned long " addr );
.BI "int arch_prctl(int " code ", unsigned long *" addr );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR arch_prctl ()
sets architecture-specific process or thread state.
diff --git a/man2/clone.2 b/man2/clone.2
index 0114668ea..0d6565b5d 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process
.fi
.PP
.IR Note :
-There is not yet a glibc wrapper for
+There is no glibc wrapper for
.BR clone3 ();
see NOTES.
.SH DESCRIPTION
diff --git a/man2/delete_module.2 b/man2/delete_module.2
index daa15faa2..e63545d51 100644
--- a/man2/delete_module.2
+++ b/man2/delete_module.2
@@ -31,7 +31,7 @@ delete_module \- unload a kernel module
.fi
.PP
.IR Note :
-No declaration of this system call is provided in glibc headers; see NOTES.
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR delete_module ()
diff --git a/man2/init_module.2 b/man2/init_module.2
index c2675db97..00cf4e948 100644
--- a/man2/init_module.2
+++ b/man2/init_module.2
@@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module
.fi
.PP
.IR Note :
-glibc provides no header file declaration of
-.BR init_module ()
-and no wrapper function for
-.BR finit_module ();
-see NOTES.
+There are no glibc wrappers for these system calls; see NOTES.
.SH DESCRIPTION
.BR init_module ()
loads an ELF image into kernel space,
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 6bf07972d..f37cae8df 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility
.BI " __kernel_ulong_t " arg5 );
.fi
.PP
-No glibc wrapper is provided for this system call; see NOTES.
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.
diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
index 1a69c8238..9312b6f92 100644
--- a/man2/pidfd_getfd.2
+++ b/man2/pidfd_getfd.2
@@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor
.nf
.BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR pidfd_getfd ()
diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
index 5b99460e1..1b0c5e0d4 100644
--- a/man2/pidfd_open.2
+++ b/man2/pidfd_open.2
@@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process
.PP
.BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR pidfd_open ()
diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
index 6670cf357..ffbfd1796 100644
--- a/man2/pidfd_send_signal.2
+++ b/man2/pidfd_send_signal.2
@@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor
.BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
.BI " unsigned int " flags );
.fi
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR pidfd_send_signal ()
diff --git a/man2/request_key.2 b/man2/request_key.2
index 86f76e43d..6b041d0c4 100644
--- a/man2/request_key.2
+++ b/man2/request_key.2
@@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility
.BI " key_serial_t " dest_keyring ");"
.fi
.PP
-No glibc wrapper is provided for this system call; see NOTES.
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.BR request_key ()
attempts to find a key of the given
diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
index b3aef858f..c3ab3bc85 100644
--- a/man2/s390_guarded_storage.2
+++ b/man2/s390_guarded_storage.2
@@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
.PP
.BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR s390_guarded_storage ()
diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
index 802142987..2ccd630ab 100644
--- a/man2/s390_pci_mmio_write.2
+++ b/man2/s390_pci_mmio_write.2
@@ -35,6 +35,9 @@ MMIO memory page
.BI "int s390_pci_mmio_read(unsigned long " mmio_addr ","
.BI " void *" user_buffer ", size_t " length ");"
.fi
+.PP
+.IR Note :
+There are no glibc wrappers for these system calls; see NOTES.
.SH DESCRIPTION
The
.BR s390_pci_mmio_write ()
diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 558e9c99d..0f4a704de 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
.PP
.BI "int s390_runtime_instr(int " command ", int " signum ");"
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR s390_runtime_instr ()
diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
index 2ff06051a..70871286b 100644
--- a/man2/s390_sthyi.2
+++ b/man2/s390_sthyi.2
@@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction
.BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ","
.BI " uint64_t *" return_code ", unsigned long " flags ");"
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR s390_sthyi ()
diff --git a/man2/seccomp.2 b/man2/seccomp.2
index 6ac890a2f..4600c51d6 100644
--- a/man2/seccomp.2
+++ b/man2/seccomp.2
@@ -41,6 +41,9 @@ seccomp \- operate on Secure Computing state of the process
.BI "int seccomp(unsigned int " operation ", unsigned int " flags \
", void *" args );
.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
The
.BR seccomp ()
diff --git a/man2/syslog.2 b/man2/syslog.2
index c6d6dcc94..133ba2121 100644
--- a/man2/syslog.2
+++ b/man2/syslog.2
@@ -36,7 +36,6 @@ set console_loglevel
.SH SYNOPSIS
.nf
.BI "int syslog(int " type ", char *" bufp ", int " len );
-.B " /* No wrapper provided in glibc */"
.PP
/* The glibc interface */
.B "#include <sys/klog.h>"
--
2.29.2
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v2 2/2] Various pages: Normalize NOTES about nonexistent glibc wrappers
2020-12-30 13:23 ` Michael Kerrisk (man-pages)
2020-12-30 15:20 ` [PATCH v2 0/2] Normalize notes about missing " Alejandro Colomar
2020-12-30 15:20 ` [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent " Alejandro Colomar
@ 2020-12-30 15:20 ` Alejandro Colomar
2020-12-30 16:07 ` Michael Kerrisk (man-pages)
2 siblings, 1 reply; 21+ messages in thread
From: Alejandro Colomar @ 2020-12-30 15:20 UTC (permalink / raw)
To: mtk.manpages; +Cc: Ganimedes Colomar, linux-man, Alejandro Colomar
From: Ganimedes Colomar <gacoan.linux@gmail.com>
See previous commit.
This commit normalizes texts under sections other than SYNOPSIS
(most of them in NOTES).
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
man2/add_key.2 | 2 +-
man2/arch_prctl.2 | 6 ++----
man2/getdents.2 | 8 ++++----
man2/io_cancel.2 | 2 +-
man2/io_destroy.2 | 2 +-
man2/io_getevents.2 | 2 +-
man2/io_setup.2 | 2 +-
man2/io_submit.2 | 2 +-
man2/kexec_load.2 | 3 +--
man2/keyctl.2 | 2 +-
man2/pidfd_getfd.2 | 2 +-
man2/pidfd_open.2 | 2 +-
man2/pidfd_send_signal.2 | 2 +-
man2/request_key.2 | 2 +-
man2/s390_guarded_storage.2 | 3 +--
man2/s390_pci_mmio_write.2 | 3 +--
man2/s390_runtime_instr.2 | 3 +--
man2/s390_sthyi.2 | 3 +--
man2/seccomp.2 | 3 +++
man2/sysctl.2 | 3 +--
20 files changed, 26 insertions(+), 31 deletions(-)
diff --git a/man2/add_key.2 b/man2/add_key.2
index 7c20de777..0d136e4aa 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -216,7 +216,7 @@ This system call first appeared in Linux 2.6.10.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
-No wrapper for this system call is provided in glibc.
+Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
.IR libkeyutils
package.
diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
index e8a6da391..f9a9dc39d 100644
--- a/man2/arch_prctl.2
+++ b/man2/arch_prctl.2
@@ -177,10 +177,8 @@ and
in the same thread is dangerous, as they may overwrite each other's
TLS entries.
.PP
-As of version 2.7, glibc provides no prototype for
-.BR arch_prctl ().
-You have to declare it yourself for now.
-This may be fixed in future glibc versions.
+Glibc does not provide a wrapper for this system call; call it using
+.BR syscall (2).
.PP
.I FS
may be already used by the threading library.
diff --git a/man2/getdents.2 b/man2/getdents.2
index 8fe6f90fc..2a0576ffd 100644
--- a/man2/getdents.2
+++ b/man2/getdents.2
@@ -211,13 +211,13 @@ SVr4.
Library support for
.BR getdents64 ()
was added in glibc 2.30;
-there is no glibc wrapper for
-.BR getdents ().
-Calling
+Glibc does not provide a wrapper for
+.BR getdents ();
+call
.BR getdents ()
(or
.BR getdents64 ()
-on earlier glibc versions) requires the use of
+on earlier glibc versions) using
.BR syscall (2).
In that case you will need to define the
.I linux_dirent
diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index 1bea257ec..8bcd9c195 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -68,7 +68,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used
in programs that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index dc9633f5a..89defd867 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -57,7 +57,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in programs
that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index c9a608e06..0f7c17dbf 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -94,7 +94,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in
programs that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index 5168ee445..e08d19bb8 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -72,7 +72,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in programs
that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/io_submit.2 b/man2/io_submit.2
index bcbcf43b9..6cdd018a5 100644
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -247,7 +247,7 @@ The asynchronous I/O system calls first appeared in Linux 2.5.
is Linux-specific and should not be used in
programs that are intended to be portable.
.SH NOTES
-Glibc does not provide a wrapper function for this system call.
+Glibc does not provide a wrapper for this system call.
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
diff --git a/man2/kexec_load.2 b/man2/kexec_load.2
index a7114545a..4951eb5c3 100644
--- a/man2/kexec_load.2
+++ b/man2/kexec_load.2
@@ -335,8 +335,7 @@ system call first appeared in Linux 3.17.
.SH CONFORMING TO
These system calls are Linux-specific.
.SH NOTES
-Currently, there is no glibc support for these system calls.
-Call them using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.SH SEE ALSO
.BR reboot (2),
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index f37cae8df..9311100cf 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -1953,7 +1953,7 @@ This system call first appeared in Linux 2.6.10.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
-No wrapper for this system call is provided in glibc.
+Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
.IR libkeyutils
library.
diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
index 9312b6f92..1a1319aae 100644
--- a/man2/pidfd_getfd.2
+++ b/man2/pidfd_getfd.2
@@ -121,7 +121,7 @@ first appeared in Linux 5.6.
.BR pidfd_getfd ()
is Linux specific.
.SH NOTES
-Currently, there is no glibc wrapper for this system call; call it using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.PP
For a description of PID file descriptors, see
diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
index 1b0c5e0d4..b6a321562 100644
--- a/man2/pidfd_open.2
+++ b/man2/pidfd_open.2
@@ -91,7 +91,7 @@ first appeared in Linux 5.3.
.BR pidfd_open ()
is Linux specific.
.SH NOTES
-Currently, there is no glibc wrapper for this system call; call it using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.PP
The following code sequence can be used to obtain a file descriptor
diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
index ffbfd1796..7b1dc782d 100644
--- a/man2/pidfd_send_signal.2
+++ b/man2/pidfd_send_signal.2
@@ -135,7 +135,7 @@ first appeared in Linux 5.1.
.BR pidfd_send_signal ()
is Linux specific.
.SH NOTES
-Currently, there is no glibc wrapper for this system call; call it using
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.\"
.SS PID file descriptors
diff --git a/man2/request_key.2 b/man2/request_key.2
index 6b041d0c4..997c221b7 100644
--- a/man2/request_key.2
+++ b/man2/request_key.2
@@ -439,7 +439,7 @@ in Linux 2.6.13.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
-No wrapper for this system call is provided in glibc.
+Glibc does not provide a wrapper for this system call.
A wrapper is provided in the
.IR libkeyutils
package.
diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
index c3ab3bc85..c20230786 100644
--- a/man2/s390_guarded_storage.2
+++ b/man2/s390_guarded_storage.2
@@ -144,9 +144,8 @@ This Linux-specific system call is available only on the s390 architecture.
.PP
The guarded storage facility is available beginning with System z14.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2)
-to call it.
.PP
The description of the guarded storage facility along with related
instructions and Guarded Storage Control Block and
diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
index 2ccd630ab..5897c967e 100644
--- a/man2/s390_pci_mmio_write.2
+++ b/man2/s390_pci_mmio_write.2
@@ -103,8 +103,7 @@ These system calls are available since Linux 3.19.
This Linux-specific system call is available only on the s390 architecture.
The required PCI support is available beginning with System z EC12.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide wrappers for these system calls; call them using
.BR syscall (2)
-to call it.
.SH SEE ALSO
.BR syscall (2)
diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
index 0f4a704de..71e391fe9 100644
--- a/man2/s390_runtime_instr.2
+++ b/man2/s390_runtime_instr.2
@@ -97,9 +97,8 @@ This Linux-specific system call is available only on the s390 architecture.
The run-time instrumentation facility is available
beginning with System z EC12.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2)
-to call it.
.PP
The
.I asm/runtime_instr.h
diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
index 70871286b..91fc622bc 100644
--- a/man2/s390_sthyi.2
+++ b/man2/s390_sthyi.2
@@ -126,9 +126,8 @@ This system call is available since Linux 4.15.
.SH CONFORMING TO
This Linux-specific system call is available only on the s390 architecture.
.SH NOTES
-Glibc does not provide a wrapper for this system call, use
+Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2)
-to call it.
.PP
For details of the STHYI instruction, see
.UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm
diff --git a/man2/seccomp.2 b/man2/seccomp.2
index 4600c51d6..181e89bfc 100644
--- a/man2/seccomp.2
+++ b/man2/seccomp.2
@@ -858,6 +858,9 @@ Tile (since Linux 4.3)
PA-RISC (since Linux 4.6)
.\" User mode Linux since Linux 4.6
.PD
+.PP
+Glibc does not provide a wrapper for this system call; call it using
+.BR syscall (2).
.\"
.SS Caveats
There are various subtleties to consider when applying seccomp filters
diff --git a/man2/sysctl.2 b/man2/sysctl.2
index 72f0af6f3..0ed68df00 100644
--- a/man2/sysctl.2
+++ b/man2/sysctl.2
@@ -120,8 +120,7 @@ Note that on older kernels where this system call still exists,
it is available only if the kernel was configured with the
.B CONFIG_SYSCTL_SYSCALL
option.
-Furthermore,
-glibc does not provide a wrapper for this system call,
+Furthermore, glibc does not provide a wrapper for this system call,
necessitating the use of
.BR syscall (2).
.SH BUGS
--
2.29.2
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v2 2/2] Various pages: Normalize NOTES about nonexistent glibc wrappers
2020-12-30 15:20 ` [PATCH v2 2/2] Various pages: Normalize NOTES " Alejandro Colomar
@ 2020-12-30 16:07 ` Michael Kerrisk (man-pages)
2020-12-30 21:01 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-30 16:07 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, Ganimedes Colomar, linux-man
Hello Alex and Ganimedes,
On 12/30/20 4:20 PM, Alejandro Colomar wrote:
> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>
> See previous commit.
>
> This commit normalizes texts under sections other than SYNOPSIS
> (most of them in NOTES).
Good! Patch applied. I made one minor fix; see below.
> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> man2/add_key.2 | 2 +-
> man2/arch_prctl.2 | 6 ++----
> man2/getdents.2 | 8 ++++----
> man2/io_cancel.2 | 2 +-
> man2/io_destroy.2 | 2 +-
> man2/io_getevents.2 | 2 +-
> man2/io_setup.2 | 2 +-
> man2/io_submit.2 | 2 +-
> man2/kexec_load.2 | 3 +--
> man2/keyctl.2 | 2 +-
> man2/pidfd_getfd.2 | 2 +-
> man2/pidfd_open.2 | 2 +-
> man2/pidfd_send_signal.2 | 2 +-
> man2/request_key.2 | 2 +-
> man2/s390_guarded_storage.2 | 3 +--
> man2/s390_pci_mmio_write.2 | 3 +--
> man2/s390_runtime_instr.2 | 3 +--
> man2/s390_sthyi.2 | 3 +--
> man2/seccomp.2 | 3 +++
> man2/sysctl.2 | 3 +--
> 20 files changed, 26 insertions(+), 31 deletions(-)
>
[...]
> --- a/man2/kexec_load.2
> +++ b/man2/kexec_load.2
> @@ -335,8 +335,7 @@ system call first appeared in Linux 3.17.
> .SH CONFORMING TO
> These system calls are Linux-specific.
> .SH NOTES
> -Currently, there is no glibc support for these system calls.
> -Call them using
> +Glibc does not provide a wrapper for this system call; call it using
I changed to: "... these system calls; call them using..."
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent glibc wrappers
2020-12-30 15:20 ` [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent " Alejandro Colomar
@ 2020-12-30 19:20 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 21+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-30 19:20 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, Ganimedes Colomar, linux-man
Hello Alex and Ganimedes,
On 12/30/20 4:20 PM, Alejandro Colomar wrote:
> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>
> To easily distinguish documentation about glibc wrappers from
> documentation about kernel syscalls, let's have a normalized
> 'Note' in the SYNOPSIS, and a further explanation in the page body
> (NOTES in most of them), as already happened in many (but not all)
> of the manual pages for syscalls without a wrapper. Furthermore,
> let's normalize the messages, following membarrier.2 (because it's
> already quite extended), so that it's easy to use grep to find
> those pages.
>
> To find these pages, we used:
> $ grep -rn wrapper man? | sort -V
> and
> $ grep -rni support.*glibc | sort -V
>
> delete_module.2, init_module.2: glibc 2.23 is no longer
> maintained, so we changed the notes about wrappers, to say that
> there are no glibc wrappers for these system calls; see NOTES.
>
> We didn't fix some obsolete pages such as create_module.2.
Thanks! Patch applied. As noted already, it's great to get
consistent language into the manual pages.
Cheers,
Michael
> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> man2/add_key.2 | 3 ++-
> man2/arch_prctl.2 | 3 +++
> man2/clone.2 | 2 +-
> man2/delete_module.2 | 2 +-
> man2/init_module.2 | 6 +-----
> man2/keyctl.2 | 3 ++-
> man2/pidfd_getfd.2 | 3 +++
> man2/pidfd_open.2 | 3 +++
> man2/pidfd_send_signal.2 | 2 ++
> man2/request_key.2 | 3 ++-
> man2/s390_guarded_storage.2 | 3 +++
> man2/s390_pci_mmio_write.2 | 3 +++
> man2/s390_runtime_instr.2 | 3 +++
> man2/s390_sthyi.2 | 3 +++
> man2/seccomp.2 | 3 +++
> man2/syslog.2 | 1 -
> 16 files changed, 35 insertions(+), 11 deletions(-)
>
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 1476b7d85..7c20de777 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -22,7 +22,8 @@ add_key \- add a key to the kernel's key management facility
> .BI " key_serial_t " keyring ");"
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR add_key ()
> creates or updates a key of the given
> diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2
> index 97d5a2fe5..e8a6da391 100644
> --- a/man2/arch_prctl.2
> +++ b/man2/arch_prctl.2
> @@ -33,6 +33,9 @@ arch_prctl \- set architecture-specific thread state
> .BI "int arch_prctl(int " code ", unsigned long " addr );
> .BI "int arch_prctl(int " code ", unsigned long *" addr );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR arch_prctl ()
> sets architecture-specific process or thread state.
> diff --git a/man2/clone.2 b/man2/clone.2
> index 0114668ea..0d6565b5d 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -60,7 +60,7 @@ clone, __clone2, clone3 \- create a child process
> .fi
> .PP
> .IR Note :
> -There is not yet a glibc wrapper for
> +There is no glibc wrapper for
> .BR clone3 ();
> see NOTES.
> .SH DESCRIPTION
> diff --git a/man2/delete_module.2 b/man2/delete_module.2
> index daa15faa2..e63545d51 100644
> --- a/man2/delete_module.2
> +++ b/man2/delete_module.2
> @@ -31,7 +31,7 @@ delete_module \- unload a kernel module
> .fi
> .PP
> .IR Note :
> -No declaration of this system call is provided in glibc headers; see NOTES.
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR delete_module ()
> diff --git a/man2/init_module.2 b/man2/init_module.2
> index c2675db97..00cf4e948 100644
> --- a/man2/init_module.2
> +++ b/man2/init_module.2
> @@ -37,11 +37,7 @@ init_module, finit_module \- load a kernel module
> .fi
> .PP
> .IR Note :
> -glibc provides no header file declaration of
> -.BR init_module ()
> -and no wrapper function for
> -.BR finit_module ();
> -see NOTES.
> +There are no glibc wrappers for these system calls; see NOTES.
> .SH DESCRIPTION
> .BR init_module ()
> loads an ELF image into kernel space,
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index 6bf07972d..f37cae8df 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -45,7 +45,8 @@ keyctl \- manipulate the kernel's key management facility
> .BI " __kernel_ulong_t " arg5 );
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR keyctl ()
> allows user-space programs to perform key manipulation.
> diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2
> index 1a69c8238..9312b6f92 100644
> --- a/man2/pidfd_getfd.2
> +++ b/man2/pidfd_getfd.2
> @@ -29,6 +29,9 @@ pidfd_getfd \- obtain a duplicate of another process's file descriptor
> .nf
> .BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_getfd ()
> diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2
> index 5b99460e1..1b0c5e0d4 100644
> --- a/man2/pidfd_open.2
> +++ b/man2/pidfd_open.2
> @@ -31,6 +31,9 @@ pidfd_open \- obtain a file descriptor that refers to a process
> .PP
> .BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_open ()
> diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2
> index 6670cf357..ffbfd1796 100644
> --- a/man2/pidfd_send_signal.2
> +++ b/man2/pidfd_send_signal.2
> @@ -32,6 +32,8 @@ pidfd_send_signal \- send a signal to a process specified by a file descriptor
> .BI "int pidfd_send_signal(int " pidfd ", int " sig ", siginfo_t *" info ,
> .BI " unsigned int " flags );
> .fi
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR pidfd_send_signal ()
> diff --git a/man2/request_key.2 b/man2/request_key.2
> index 86f76e43d..6b041d0c4 100644
> --- a/man2/request_key.2
> +++ b/man2/request_key.2
> @@ -22,7 +22,8 @@ request_key \- request a key from the kernel's key management facility
> .BI " key_serial_t " dest_keyring ");"
> .fi
> .PP
> -No glibc wrapper is provided for this system call; see NOTES.
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> .BR request_key ()
> attempts to find a key of the given
> diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2
> index b3aef858f..c3ab3bc85 100644
> --- a/man2/s390_guarded_storage.2
> +++ b/man2/s390_guarded_storage.2
> @@ -31,6 +31,9 @@ s390_guarded_storage \- operations with z/Architecture guarded storage facility
> .PP
> .BI "int s390_guarded_storage(int " command ", struct gs_cb *" gs_cb ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_guarded_storage ()
> diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2
> index 802142987..2ccd630ab 100644
> --- a/man2/s390_pci_mmio_write.2
> +++ b/man2/s390_pci_mmio_write.2
> @@ -35,6 +35,9 @@ MMIO memory page
> .BI "int s390_pci_mmio_read(unsigned long " mmio_addr ","
> .BI " void *" user_buffer ", size_t " length ");"
> .fi
> +.PP
> +.IR Note :
> +There are no glibc wrappers for these system calls; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_pci_mmio_write ()
> diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2
> index 558e9c99d..0f4a704de 100644
> --- a/man2/s390_runtime_instr.2
> +++ b/man2/s390_runtime_instr.2
> @@ -31,6 +31,9 @@ s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation
> .PP
> .BI "int s390_runtime_instr(int " command ", int " signum ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_runtime_instr ()
> diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
> index 2ff06051a..70871286b 100644
> --- a/man2/s390_sthyi.2
> +++ b/man2/s390_sthyi.2
> @@ -32,6 +32,9 @@ s390_sthyi \- emulate STHYI instruction
> .BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ","
> .BI " uint64_t *" return_code ", unsigned long " flags ");"
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR s390_sthyi ()
> diff --git a/man2/seccomp.2 b/man2/seccomp.2
> index 6ac890a2f..4600c51d6 100644
> --- a/man2/seccomp.2
> +++ b/man2/seccomp.2
> @@ -41,6 +41,9 @@ seccomp \- operate on Secure Computing state of the process
> .BI "int seccomp(unsigned int " operation ", unsigned int " flags \
> ", void *" args );
> .fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call; see NOTES.
> .SH DESCRIPTION
> The
> .BR seccomp ()
> diff --git a/man2/syslog.2 b/man2/syslog.2
> index c6d6dcc94..133ba2121 100644
> --- a/man2/syslog.2
> +++ b/man2/syslog.2
> @@ -36,7 +36,6 @@ set console_loglevel
> .SH SYNOPSIS
> .nf
> .BI "int syslog(int " type ", char *" bufp ", int " len );
> -.B " /* No wrapper provided in glibc */"
> .PP
> /* The glibc interface */
> .B "#include <sys/klog.h>"
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v2 2/2] Various pages: Normalize NOTES about nonexistent glibc wrappers
2020-12-30 16:07 ` Michael Kerrisk (man-pages)
@ 2020-12-30 21:01 ` Alejandro Colomar (man-pages)
0 siblings, 0 replies; 21+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-30 21:01 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: Ganimedes Colomar, linux-man
On 12/30/20 5:07 PM, Michael Kerrisk (man-pages) wrote:
> Hello Alex and Ganimedes,
>
> On 12/30/20 4:20 PM, Alejandro Colomar wrote:
>> From: Ganimedes Colomar <gacoan.linux@gmail.com>
>>
>> See previous commit.
>>
>> This commit normalizes texts under sections other than SYNOPSIS
>> (most of them in NOTES).
>
> Good! Patch applied. I made one minor fix; see below.
>
>> Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
>> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>> man2/add_key.2 | 2 +-
>> man2/arch_prctl.2 | 6 ++----
>> man2/getdents.2 | 8 ++++----
>> man2/io_cancel.2 | 2 +-
>> man2/io_destroy.2 | 2 +-
>> man2/io_getevents.2 | 2 +-
>> man2/io_setup.2 | 2 +-
>> man2/io_submit.2 | 2 +-
>> man2/kexec_load.2 | 3 +--
>> man2/keyctl.2 | 2 +-
>> man2/pidfd_getfd.2 | 2 +-
>> man2/pidfd_open.2 | 2 +-
>> man2/pidfd_send_signal.2 | 2 +-
>> man2/request_key.2 | 2 +-
>> man2/s390_guarded_storage.2 | 3 +--
>> man2/s390_pci_mmio_write.2 | 3 +--
>> man2/s390_runtime_instr.2 | 3 +--
>> man2/s390_sthyi.2 | 3 +--
>> man2/seccomp.2 | 3 +++
>> man2/sysctl.2 | 3 +--
>> 20 files changed, 26 insertions(+), 31 deletions(-)
>>
>
> [...]
>
>> --- a/man2/kexec_load.2
>> +++ b/man2/kexec_load.2
>> @@ -335,8 +335,7 @@ system call first appeared in Linux 3.17.
>> .SH CONFORMING TO
>> These system calls are Linux-specific.
>> .SH NOTES
>> -Currently, there is no glibc support for these system calls.
>> -Call them using
>> +Glibc does not provide a wrapper for this system call; call it using
>
> I changed to: "... these system calls; call them using..."
Hello Michael,
Good catch!
I'll send you a first round of fixes for syscalls and wrappers in a moment.
Thanks,
Alex
>
> Thanks,
>
> Michael
>
^ permalink raw reply [flat|nested] 21+ messages in thread
end of thread, other threads:[~2020-12-30 21:02 UTC | newest]
Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-29 14:38 [PATCH 0/2] Normalize notes about missing glibc wrappers Alejandro Colomar
2020-12-29 14:39 ` [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing " Alejandro Colomar
2020-12-29 14:49 ` Alejandro Colomar (man-pages)
2020-12-29 20:27 ` Michael Kerrisk (man-pages)
2020-12-29 20:51 ` Alejandro Colomar (man-pages)
2020-12-30 9:37 ` Michael Kerrisk (man-pages)
2020-12-29 14:39 ` [PATCH 2/2] Various pages: Normalize NOTES " Alejandro Colomar
2020-12-29 20:32 ` Michael Kerrisk (man-pages)
2020-12-29 20:53 ` Alejandro Colomar (man-pages)
2020-12-30 9:38 ` Michael Kerrisk (man-pages)
2020-12-30 12:52 ` Alejandro Colomar (man-pages)
2020-12-30 13:23 ` Michael Kerrisk (man-pages)
2020-12-30 15:20 ` [PATCH v2 0/2] Normalize notes about missing " Alejandro Colomar
2020-12-30 15:20 ` [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent " Alejandro Colomar
2020-12-30 19:20 ` Michael Kerrisk (man-pages)
2020-12-30 15:20 ` [PATCH v2 2/2] Various pages: Normalize NOTES " Alejandro Colomar
2020-12-30 16:07 ` Michael Kerrisk (man-pages)
2020-12-30 21:01 ` Alejandro Colomar (man-pages)
2020-12-29 20:19 ` [PATCH 0/2] Normalize notes about missing " Michael Kerrisk (man-pages)
2020-12-29 20:45 ` Alejandro Colomar (man-pages)
2020-12-30 9:30 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.