Skip to contentSkip to conversation

man[23]/: Add LIBRARY section

RFC PATCH New Alejandro Colomar 1 participant 5 messages May 21, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Alejandro Colomar

author
#0 lore raw

cover man[23]/: Add LIBRARY section

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(-)
Signature · 1 line
2.31.1
author
#1 lore raw

PATCH 1/4 _exit.2: Add LIBRARY section

Signed-off-by Alejandro Colomar <[email protected]>
---
 man2/_exit.2 | 3 +++
 1 file changed, 3 insertions(+)
man2/_exit.2 +3 -0
index 6d9067eb6..38ee1d7ec 100644
@@ -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>
Signature · 1 line
2.31.1
author
#2 lore raw

PATCH 2/4 keyctl.2: Add LIBRARY section

In reply to Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
---
 man2/keyctl.2 | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
man2/keyctl.2 +7 -2
index 7f5fcb951..4b4eeee04 100644
@@ -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.
Signature · 1 line
2.31.1
author
#3 lore raw

PATCH 3/4 gamma.3: Add LIBRARY section

In reply to Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
---
 man3/gamma.3 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
man3/gamma.3 +3 -2
index 003964158..49f66427b 100644
@@ -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)):
Signature · 1 line
2.31.1
author
#4 lore raw

PATCH 4/4 request_key.2: Add LIBRARY section

In reply to Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
---
 man2/request_key.2 | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)
man2/request_key.2 +4 -11
index ea23e7ed5..c49d05e46 100644
@@ -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 ().
Signature · 1 line
2.31.1