[RFC PATCH 0/4] man[23]/: Add LIBRARY section

[RFC PATCH 0/4] man[23]/: Add LIBRARY section

[Alejandro Colomar]

Hi Michael,

As I told you some time ago, I liked the style of FreeBSD for specifying
where a function comes from.  See for example:
<https://www.freebsd.org/cgi/man.cgi?query=open&apropos=0&sektion=2&manpath=FreeBSD+12.2-RELEASE+and+Ports&arch=default&format=html>
and
<https://www.freebsd.org/cgi/man.cgi?query=gamma&apropos=0&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports&arch=default&format=html>.

I wrote a few pages to cover most cases:
- A syscall needing syscall(2).
- A syscall wrapped by a library other than glibc.
- A syscall wrapped by glibc.
- A math function.

What do you think about it?

Cheers,

Alex

Alejandro Colomar (4):
  _exit.2: Add LIBRARY section
  keyctl.2: Add LIBRARY section
  gamma.3: Add LIBRARY section
  request_key.2: Add LIBRARY section

 man2/_exit.2       |  3 +++
 man2/keyctl.2      |  9 +++++++--
 man2/request_key.2 | 15 ++++-----------
 man3/gamma.3       |  5 +++--
 4 files changed, 17 insertions(+), 15 deletions(-)

-- 
2.31.1

[PATCH 1/4] _exit.2: Add LIBRARY section

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/_exit.2 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man2/_exit.2 b/man2/_exit.2
index 6d9067eb6..38ee1d7ec 100644
--- a/man2/_exit.2
+++ b/man2/_exit.2
@@ -29,6 +29,9 @@
 .TH _EXIT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
 .SH NAME
 _exit, _Exit \- terminate the calling process
+.SH LIBRARY
+glibc - standard C library
+.RI ( libc ", " -lc )
 .SH SYNOPSIS
 .nf
 .B #include <unistd.h>
-- 
2.31.1

[PATCH 2/4] keyctl.2: Add LIBRARY section

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/keyctl.2 | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 7f5fcb951..4b4eeee04 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -28,6 +28,13 @@
 .TH KEYCTL 2 2021-03-22 Linux "Linux Key Management Calls"
 .SH NAME
 keyctl \- manipulate the kernel's key management facility
+.SH LIBRARY
+Linux kernel, glibc - standard C library
+.RI ( libc ", " -lc )
+.PP
+Alternatively, libkeyutils
+.RI ( libkeyutils ", " -lkeyutils );
+see NOTES.
 .SH SYNOPSIS
 .nf
 .BR "#include <linux/keyctl.h>" "     /* Definition of " KEY* " constants */"
@@ -1955,8 +1962,6 @@ This system call is a nonstandard Linux extension.
 A wrapper is provided in the
 .IR libkeyutils
 library.
-When employing the wrapper in that library, link with
-.IR \-lkeyutils .
 However, rather than using this system call directly,
 you probably want to use the various library functions
 mentioned in the descriptions of individual operations above.
-- 
2.31.1

[PATCH 3/4] gamma.3: Add LIBRARY section

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/gamma.3 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man3/gamma.3 b/man3/gamma.3
index 003964158..49f66427b 100644
--- a/man3/gamma.3
+++ b/man3/gamma.3
@@ -9,6 +9,9 @@
 .TH GAMMA 3 2021-03-22 "GNU" "Linux Programmer's Manual"
 .SH NAME
 gamma, gammaf, gammal \- (logarithm of the) gamma function
+.SH LIBRARY
+glibc - math library
+.RI ( libm ", " -lm )
 .SH SYNOPSIS
 .nf
 .B #include <math.h>
@@ -18,8 +21,6 @@ gamma, gammaf, gammal \- (logarithm of the) gamma function
 .BI "long double gammal(long double " x ");"
 .fi
 .PP
-Link with \fI\-lm\fP.
-.PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
-- 
2.31.1

[PATCH 4/4] request_key.2: Add LIBRARY section

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/request_key.2 | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/man2/request_key.2 b/man2/request_key.2
index ea23e7ed5..c49d05e46 100644
--- a/man2/request_key.2
+++ b/man2/request_key.2
@@ -12,17 +12,17 @@
 .TH REQUEST_KEY 2 2021-03-22 Linux "Linux Key Management Calls"
 .SH NAME
 request_key \- request a key from the kernel's key management facility
+.SH LIBRARY
+libkeyutils
+.RI ( libkeyutils ", " -lkeyutils )
 .SH SYNOPSIS
 .nf
 .B #include <keyutils.h>
 .PP
 .BI "key_serial_t request_key(const char *" type ", const char *" description ,
 .BI "                         const char *" callout_info ,
-.BI "                         key_serial_t " dest_keyring ");"
+.BI "                         key_serial_t " dest_keyring );
 .fi
-.PP
-.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
@@ -437,13 +437,6 @@ The ability to instantiate keys upon request was added
 in Linux 2.6.13.
 .SH CONFORMING TO
 This system call is a nonstandard Linux extension.
-.SH NOTES
-Glibc does not provide a wrapper for this system call.
-A wrapper is provided in the
-.IR libkeyutils
-package.
-When employing the wrapper in that library, link with
-.IR \-lkeyutils .
 .SH EXAMPLES
 The program below demonstrates the use of
 .BR request_key ().
-- 
2.31.1