Hi наб!
On Mon, Aug 12, 2024 at 07:23:08PM GMT, наб wrote:
> There's no point documenting this syscall at any point in time,
> because it changed constantly. A post-mortem summary I believe to be
> comprehensive is included below.
>
[...]
>
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@xxxxxxxxxxxxxxxxxx>
> ---
> man/man2/bdflush.2 | 97 ++++++++++-----------------------------------
> man/man2/syscalls.2 | 3 +-
> 2 files changed, 22 insertions(+), 78 deletions(-)
>
> diff --git a/man/man2/bdflush.2 b/man/man2/bdflush.2
> index 8627a42a2..c4c6400ff 100644
> --- a/man/man2/bdflush.2
> +++ b/man/man2/bdflush.2
> @@ -12,91 +12,34 @@ .SH SYNOPSIS
> .nf
> .B #include <sys/kdaemon.h>
> .P
> -.BI "[[deprecated]] int bdflush(int " func ", long *" address );
> -.BI "[[deprecated]] int bdflush(int " func ", long " data );
> +.BI "int bdflush(int " func ", long " data );
> +.RI "// if " func " is even, " data " actually represents a pointer)"
I prefer that comment as a paragraph within DESCRIPTION, I think.
> .fi
> .SH DESCRIPTION
> -.IR Note :
> -Since Linux 2.6,
> -.\" As noted in changes in the 2.5.12 source
> -this system call is deprecated and does nothing.
> -It is likely to disappear altogether in a future kernel release.
> -Nowadays, the task performed by
> -.BR bdflush ()
> -is handled by the kernel
> -.I pdflush
> -thread.
> +This system call was introduced in Linux 1.1.3,
> +became effectively obsolete in Linux 1.3.50,
> +mostly useless in Linux 2.3.23,
> +entirely useless in Linux 2.5.12,
> +officially deprecated in Linux 2.5.52,
> +and removed outright in Linux 5.15.
Should that go into HISTORY and just leave here a first paragraph saying
it doesn't exist anymore in DESCRIPTION?
> .P
> -.BR bdflush ()
> -starts, flushes, or tunes the buffer-dirty-flush daemon.
> -Only a privileged process (one with the
> -.B CAP_SYS_ADMIN
> -capability) may call
> -.BR bdflush ().
> +It used to turn the calling process into the
> +.I bdflush
> +daemon,
> +or tune it,
> +or flush the "old buffers".
> +It then progressively lost all of that functionality.
> .P
> -If
> -.I func
> -is negative or 0, and no daemon has been started, then
> -.BR bdflush ()
> -enters the daemon code and never returns.
> -.P
> -If
> -.I func
> -is 1,
> -some dirty buffers are written to disk.
> -.P
> -If
> -.I func
> -is 2 or more and is even (low bit is 0), then
> -.I address
> -is the address of a long word,
> -and the tuning parameter numbered
> -.RI "(" "func" "\-2)/2"
> -is returned to the caller in that address.
> -.P
> -If
> -.I func
> -is 3 or more and is odd (low bit is 1), then
> -.I data
> -is a long word,
> -and the kernel sets tuning parameter numbered
> -.RI "(" "func" "\-3)/2"
> -to that value.
> -.P
> -The set of parameters, their values, and their valid ranges
> -are defined in the Linux kernel source file
> -.IR fs/buffer.c .
> -.SH RETURN VALUE
> -If
> -.I func
> -is negative or 0 and the daemon successfully starts,
> -.BR bdflush ()
> -never returns.
> -Otherwise, the return value is 0 on success and \-1 on failure, with
> -.I errno
> -set to indicate the error.
> +See
> +.I fs/buffer.c
> +in the kernel version you're interested in to see what it actually does there.
> .SH ERRORS
> -.TP
> -.B EBUSY
> -An attempt was made to enter the daemon code after
> -another process has already entered.
> -.TP
> -.B EFAULT
> -.I address
> -points outside your accessible address space.
> -.TP
> -.B EINVAL
> -An attempt was made to read or write an invalid parameter number,
> -or to write an invalid value to a parameter.
> -.TP
> -.B EPERM
> -Caller does not have the
> -.B CAP_SYS_ADMIN
> -capability.
> +.B ENOSYS
> +(this system call is unimplemented)
I would keep the old errors around, in case someone needs to debug an
old system.
Cheers,
Alex
> .SH STANDARDS
> Linux.
> .SH HISTORY
> -Since glibc 2.23, glibc no longer supports this obsolete system call.
> +The header and prototype were removed in glibc 2.23.
> .SH SEE ALSO
> .BR sync (1),
> .BR fsync (2),
> diff --git a/man/man2/syscalls.2 b/man/man2/syscalls.2
> index 795a3f7be..325ecf5ac 100644
> --- a/man/man2/syscalls.2
> +++ b/man/man2/syscalls.2
> @@ -170,7 +170,8 @@ .SS System call list
> \fBatomic_cmpxchg_32\fP(2) 2.6.34 m68k only
> \fBbdflush\fP(2) 1.2 T{
> Deprecated (does nothing)
> -since 2.6
> +since 2.6,
> +removed in 5.15
> T}
> \fBbind\fP(2) 2.0 T{
> See notes on \fBsocketcall\fP(2)
> --
> 2.39.2
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
