Normalize notes about missing glibc wrappers
cover Normalize notes about missing glibc wrappers
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
Signature · 1 line
2.29.2
PATCH 1/2 Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
From: Ganimedes Colomar <[email protected]>
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.
---
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(-)
man2/add_key.2 +2 -1
@@ -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
man2/arch_prctl.2 +3 -0
@@ -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.
man2/clone.2 +1 -1
@@ -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
man2/delete_module.2 +1 -1
@@ -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 ()
man2/init_module.2 +1 -5
@@ -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,
man2/keyctl.2 +2 -1
@@ -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.
man2/pidfd_getfd.2 +3 -0
@@ -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 ()
man2/pidfd_open.2 +3 -0
@@ -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 ()
man2/pidfd_send_signal.2 +2 -0
@@ -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 ()
man2/request_key.2 +2 -1
@@ -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
man2/s390_guarded_storage.2 +3 -0
@@ -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 ()
man2/s390_pci_mmio_write.2 +3 -0
@@ -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 ()
man2/s390_runtime_instr.2 +3 -0
@@ -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 ()
man2/s390_sthyi.2 +3 -0
@@ -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 ()
Signature · 1 line
2.29.2
Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
Hi Michael,
a few comments below.
Cheers,
Alex
Quoted 16 lines · Alejandro Colomar
From: Ganimedes Colomar <[email protected]>
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
Quoted 6 lines
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 :)
Quoted 7 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
Quoted 7 lines
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?
Quoted 218 lines
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(-)man2/add_key.2 +2
-1@@ -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 givenman2/arch_prctl.2 +3
-0@@ -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.man2/clone.2 +1
-1@@ -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 DESCRIPTIONman2/delete_module.2 +1
-1@@ -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 ()man2/init_module.2 +1
-5@@ -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,man2/keyctl.2 +2
-1@@ -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.man2/pidfd_getfd.2 +3
-0@@ -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 ()man2/pidfd_open.2 +3
-0@@ -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 ()man2/pidfd_send_signal.2 +2
-0@@ -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 ()man2/request_key.2 +2
-1@@ -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 givenman2/s390_guarded_storage.2 +3
-0@@ -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 ()man2/s390_pci_mmio_write.2 +3
-0@@ -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 ()man2/s390_runtime_instr.2 +3
-0@@ -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 ()man2/s390_sthyi.2 +3
-0@@ -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 ()
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
In reply to Alejandro ColomarHi Alex, Ganimedes.
In the subject line : s/non-existing/nonexistent/
Quoted 12 lines · Alejandro Colomar
From: Ganimedes Colomar <[email protected]>
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.
Quoted 8 lines
To find these pages, we used:
$ grep -rn wrapper man? | sort -V and $ grep -rni support.*glibc | sort -Vdelete_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.
Quoted 2 lines
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
Quoted 234 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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(-)man2/add_key.2 +2
-1@@ -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 givenman2/arch_prctl.2 +3
-0@@ -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.man2/clone.2 +1
-1@@ -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 DESCRIPTIONman2/delete_module.2 +1
-1@@ -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 ()man2/init_module.2 +1
-5@@ -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,man2/keyctl.2 +2
-1@@ -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.man2/pidfd_getfd.2 +3
-0@@ -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 ()man2/pidfd_open.2 +3
-0@@ -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 ()man2/pidfd_send_signal.2 +2
-0@@ -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 ()man2/request_key.2 +2
-1@@ -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 givenman2/s390_guarded_storage.2 +3
-0@@ -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 ()man2/s390_pci_mmio_write.2 +3
-0@@ -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 ()man2/s390_runtime_instr.2 +3
-0@@ -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 ()man2/s390_sthyi.2 +3
-1@@ -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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
Hello Michael,
A question below.
Cheers,
Alex
Quoted 3 lines · Michael Kerrisk (man-pages)
Hi Alex, Ganimedes.
In the subject line : s/non-existing/nonexistent/
Ok, I'll resend in a few minutes.
Quoted 30 lines · Alejandro Colomar
Quoted 12 lines
From: Ganimedes Colomar <[email protected]>
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.
Quoted 8 lines
To find these pages, we used:
$ grep -rn wrapper man? | sort -V and $ grep -rni support.*glibc | sort -Vdelete_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.
Quoted 2 lines
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.
Quoted 25 lines
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
Quoted 14 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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);Quoted 222 lines
Quoted 220 lines
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(-)man2/add_key.2 +2
-1@@ -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 givenman2/arch_prctl.2 +3
-0@@ -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.man2/clone.2 +1
-1@@ -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 DESCRIPTIONman2/delete_module.2 +1
-1@@ -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 ()man2/init_module.2 +1
-5@@ -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,man2/keyctl.2 +2
-1@@ -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.man2/pidfd_getfd.2 +3
-0@@ -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 ()man2/pidfd_open.2 +3
-0@@ -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 ()man2/pidfd_send_signal.2 +2
-0@@ -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 ()man2/request_key.2 +2
-1@@ -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 givenman2/s390_guarded_storage.2 +3
-0@@ -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 ()man2/s390_pci_mmio_write.2 +3
-0@@ -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 ()man2/s390_runtime_instr.2 +3
-0@@ -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 ()man2/s390_sthyi.2 +3
-1@@ -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
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Re: [PATCH 1/2] Various pages: Normalize SYNOPSIS notes about non-existing glibc wrappers
Hi Alex,
Quoted 74 lines · Alejandro Colomar (man-pages)
Hello Michael,
A question below.
Cheers,
Alex
Quoted 3 lines · Michael Kerrisk (man-pages)
Hi Alex, Ganimedes.
In the subject line : s/non-existing/nonexistent/
Ok, I'll resend in a few minutes.
Quoted 30 lines · Alejandro Colomar
Quoted 12 lines
From: Ganimedes Colomar <[email protected]>
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.
Quoted 8 lines
To find these pages, we used:
$ grep -rn wrapper man? | sort -V and $ grep -rni support.*glibc | sort -Vdelete_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.
Quoted 2 lines
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.
Quoted 25 lines
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
Quoted 14 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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?
Quoted 7 lines
$ 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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH 2/2 Various pages: Normalize NOTES about non-existing glibc wrappers
In reply to Alejandro ColomarFrom: Ganimedes Colomar <[email protected]>
See previous commit.
This commit normalizes texts under sections other than SYNOPSIS (most of them in NOTES).
--- 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(-)
man2/add_key.2 +1 -1
@@ -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.
man2/arch_prctl.2 +2 -4
@@ -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.
man2/getdents.2 +4 -4
@@ -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
man2/io_cancel.2 +1 -1
@@ -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
man2/io_destroy.2 +1 -1
@@ -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
man2/io_getevents.2 +1 -1
@@ -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
man2/io_setup.2 +1 -1
@@ -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
man2/io_submit.2 +1 -1
@@ -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
man2/kexec_load.2 +1 -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),
man2/keyctl.2 +1 -1
@@ -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.
man2/pidfd_getfd.2 +1 -1
@@ -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
man2/pidfd_open.2 +1 -1
@@ -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
man2/pidfd_send_signal.2 +1 -1
@@ -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
man2/request_key.2 +1 -1
@@ -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.
man2/s390_guarded_storage.2 +1 -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
man2/s390_pci_mmio_write.2 +1 -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)
man2/s390_runtime_instr.2 +1 -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
man2/s390_sthyi.2 +1 -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
man2/sysctl.2 +1 -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
Signature · 1 line
2.29.2
Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
Hi Alex, Ganimedes,
Again, in the subject line, s/
non-existing/nonexistent/
[...]
man2/getdents.2 SVr4. · line 216
Quoted 12 lines
man2/getdents.2 +3
-3@@ -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/
man2/getdents.2 SVr4. · line 223
Quoted 8 lines
man2/getdents.2 +1
-1.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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
Hi Michael,
Please, see a comment below.
Thanks,
Alex
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Alex, Ganimedes,
Again, in the subject line, s/
non-existing/nonexistent/
[...]
Quoted 14 lines
man2/getdents.2 SVr4. · line 216
Quoted 12 lines
man2/getdents.2 +3
-3@@ -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 (); +calls/call/calling/
See below
Quoted 6 lines
man2/getdents.2 SVr4. · line 220
Quoted 6 lines
man2/getdents.2 +1
-1.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).'.
Quoted 14 lines
man2/getdents.2 SVr4. · line 223
Quoted 3 lines
man2/getdents.2 +0
-0.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
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
Hi Alex,
Quoted 36 lines · Alejandro Colomar (man-pages)
Hi Michael,
Please, see a comment below.
Thanks,
Alex
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Alex, Ganimedes,
Again, in the subject line, s/
non-existing/nonexistent/
[...]
Quoted 14 lines
man2/getdents.2 SVr4. · line 216
Quoted 12 lines
man2/getdents.2 +3
-3@@ -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 (); +calls/call/calling/
See below
Quoted 1 line
Quoted 7 lines
Quoted 5 lines
man2/getdents.2 SVr4. · line 220
Quoted 5 lines
man2/getdents.2 +1
-1.BR getdents () (or .BR getdents64 () -on earlier glibc versions) requires the use of +on earlier glibc versions) usingThe new version is 'Call XXX using syscall(2).'.
I need more context here please. What do you mean with "The new version"?
Thanks,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
Quoted 48 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 36 lines · Alejandro Colomar (man-pages)
Hi Michael,
Please, see a comment below.
Thanks,
Alex
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Alex, Ganimedes,
Again, in the subject line, s/
non-existing/nonexistent/
[...]
Quoted 14 lines
man2/getdents.2 SVr4. · line 216
Quoted 12 lines
man2/getdents.2 +3
-3@@ -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 (); +calls/call/calling/
See below
Quoted 1 line
Quoted 7 lines
Quoted 5 lines
man2/getdents.2 SVr4. · line 220
Quoted 5 lines
man2/getdents.2 +1
-1.BR getdents () (or .BR getdents64 () -on earlier glibc versions) requires the use of +on earlier glibc versions) usingThe new version is 'Call XXX using syscall(2).'.
Quoted 1 line
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
Quoted 6 lines
Thanks,
Michael
Re: [PATCH 2/2] Various pages: Normalize NOTES about non-existing glibc wrappers
Quoted 53 lines · Alejandro Colomar (man-pages)
Quoted 48 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 36 lines · Alejandro Colomar (man-pages)
Hi Michael,
Please, see a comment below.
Thanks,
Alex
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Alex, Ganimedes,
Again, in the subject line, s/
non-existing/nonexistent/
[...]
Quoted 14 lines
man2/getdents.2 SVr4. · line 216
Quoted 12 lines
man2/getdents.2 +3
-3@@ -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 (); +calls/call/calling/
See below
Quoted 1 line
Quoted 7 lines
Quoted 5 lines
man2/getdents.2 SVr4. · line 220
Quoted 5 lines
man2/getdents.2 +1
-1.BR getdents () (or .BR getdents64 () -on earlier glibc versions) requires the use of +on earlier glibc versions) usingThe new version is 'Call XXX using syscall(2).'.
Quoted 1 line
I need more context here please. What do you mean with "The new version"?
Quoted 8 lines
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
v2 cover Normalize notes about missing glibc wrappers
* 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(-)
Signature · 1 line
2.29.2
PATCH v2 1/2 Various pages: Normalize SYNOPSIS notes about nonexistent glibc wrappers
In reply to Michael Kerrisk (man-pages)From: Ganimedes Colomar <[email protected]>
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.
--- 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(-)
man2/add_key.2 +2 -1
@@ -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
man2/arch_prctl.2 +3 -0
@@ -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.
man2/clone.2 +1 -1
@@ -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
man2/delete_module.2 +1 -1
@@ -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 ()
man2/init_module.2 +1 -5
@@ -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,
man2/keyctl.2 +2 -1
@@ -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.
man2/pidfd_getfd.2 +3 -0
@@ -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 ()
man2/pidfd_open.2 +3 -0
@@ -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 ()
man2/pidfd_send_signal.2 +2 -0
@@ -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 ()
man2/request_key.2 +2 -1
@@ -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
man2/s390_guarded_storage.2 +3 -0
@@ -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 ()
man2/s390_pci_mmio_write.2 +3 -0
@@ -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 ()
man2/s390_runtime_instr.2 +3 -0
@@ -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 ()
man2/s390_sthyi.2 +3 -0
@@ -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 ()
man2/seccomp.2 +3 -0
@@ -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 ()
man2/syslog.2 +0 -1
@@ -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>"
Signature · 1 line
2.29.2
Re: [PATCH v2 1/2] Various pages: Normalize SYNOPSIS notes about nonexistent glibc wrappers
Hello Alex and Ganimedes,
Quoted 16 lines · Alejandro Colomar
From: Ganimedes Colomar <[email protected]>
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
Quoted 5 lines
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
Quoted 245 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>--- 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(-)man2/add_key.2 +2
-1@@ -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 givenman2/arch_prctl.2 +3
-0@@ -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.man2/clone.2 +1
-1@@ -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 DESCRIPTIONman2/delete_module.2 +1
-1@@ -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 ()man2/init_module.2 +1
-5@@ -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,man2/keyctl.2 +2
-1@@ -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.man2/pidfd_getfd.2 +3
-0@@ -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 ()man2/pidfd_open.2 +3
-0@@ -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 ()man2/pidfd_send_signal.2 +2
-0@@ -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 ()man2/request_key.2 +2
-1@@ -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 givenman2/s390_guarded_storage.2 +3
-0@@ -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 ()man2/s390_pci_mmio_write.2 +3
-0@@ -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 ()man2/s390_runtime_instr.2 +3
-0@@ -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 ()man2/s390_sthyi.2 +3
-0@@ -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 ()man2/seccomp.2 +3
-0@@ -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 ()man2/syslog.2 +0
-1@@ -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>"
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH v2 2/2 Various pages: Normalize NOTES about nonexistent glibc wrappers
In reply to Michael Kerrisk (man-pages)From: Ganimedes Colomar <[email protected]>
See previous commit.
This commit normalizes texts under sections other than SYNOPSIS (most of them in NOTES).
--- 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(-)
man2/add_key.2 +1 -1
@@ -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.
man2/arch_prctl.2 +2 -4
@@ -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.
man2/getdents.2 +4 -4
@@ -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
man2/io_cancel.2 +1 -1
@@ -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
man2/io_destroy.2 +1 -1
@@ -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
man2/io_getevents.2 +1 -1
@@ -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
man2/io_setup.2 +1 -1
@@ -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
man2/io_submit.2 +1 -1
@@ -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
man2/kexec_load.2 +1 -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),
man2/keyctl.2 +1 -1
@@ -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.
man2/pidfd_getfd.2 +1 -1
@@ -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
man2/pidfd_open.2 +1 -1
@@ -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
man2/pidfd_send_signal.2 +1 -1
@@ -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
man2/request_key.2 +1 -1
@@ -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.
man2/s390_guarded_storage.2 +1 -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
man2/s390_pci_mmio_write.2 +1 -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)
man2/s390_runtime_instr.2 +1 -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
man2/s390_sthyi.2 +1 -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
man2/seccomp.2 +3 -0
@@ -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
man2/sysctl.2 +1 -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
Signature · 1 line
2.29.2
Re: [PATCH v2 2/2] Various pages: Normalize NOTES about nonexistent glibc wrappers
Hello Alex and Ganimedes,
Quoted 6 lines · Alejandro Colomar
From: Ganimedes Colomar <[email protected]>
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.
Quoted 26 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>--- 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(-)
[...]
man2/kexec_load.2 system call first appeared in Linux 3.17. · line 338
Quoted 9 lines
man2/kexec_load.2 +1
-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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH v2 2/2] Various pages: Normalize NOTES about nonexistent glibc wrappers
Quoted 41 lines · Michael Kerrisk (man-pages)
Hello Alex and Ganimedes,
Quoted 6 lines · Alejandro Colomar
From: Ganimedes Colomar <[email protected]>
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.
Quoted 26 lines
Signed-off-by Ganimedes Colomar <[email protected]>Cowritten-by Alejandro Colomar <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>--- 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(-)[...]
Quoted 11 lines
man2/kexec_load.2 system call first appeared in Linux 3.17. · line 338
Quoted 9 lines
man2/kexec_load.2 +1
-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 usingI 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
Quoted 5 lines
Thanks,
Michael
Hi Alex, hi Ganimedes!
Quoted 4 lines · Alejandro Colomar
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.
Quoted 1 line
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
Quoted 41 lines
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 wrappersman2/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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 12 lines · Michael Kerrisk (man-pages)
Hi Alex, hi Ganimedes!
Quoted 4 lines · Alejandro Colomar
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.
Quoted 6 lines
Quoted 1 line
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
Quoted 50 lines
?
Thanks,
Michael
Quoted 41 lines
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 wrappersman2/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
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Hi Alex,
Quoted 23 lines · Alejandro Colomar (man-pages)
Quoted 12 lines · Michael Kerrisk (man-pages)
Hi Alex, hi Ganimedes!
Quoted 4 lines · Alejandro Colomar
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.
Quoted 6 lines
Quoted 1 line
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)
Quoted 7 lines
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_tone).), 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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/