[PATCH 0/6] man[23]: SYNOPSIS: Use 'noreturn' in prototypes.

[PATCH 0/6] man[23]: SYNOPSIS: Use 'noreturn' in prototypes.

[Alejandro Colomar]

Hi Michael,

Here's a patch for using 'noreturn' in the prototypes that never return,
such as exit(), abort(), longjmp(), etc, using standard C (C11) syntax.

This patch set fixes all of man2 and man3.

Cheers,

Alex

......

This was useful:

.../glibc$ man_lsfunc ../../linux/man-pages/man[23] \
           |while read -r syscall; do
           	echo "=============================  ${syscall}";
           	grep_glibc_prototype ${syscall} \
           	|sed -e 's/\bextern //' \
           	|pcregrep -M '(?s).*noreturn.*';
           done \
           |less;

---
Alejandro Colomar (6):
  abort.3: SYNOPSIS: Use 'noreturn' in prototypes
  _exit.2: SYNOPSIS: Use 'noreturn' in prototypes
  err.3: SYNOPSIS: Use 'noreturn' in prototypes
  exit.3: SYNOPSIS: Use 'noreturn' in prototypes
  pthread_exit.3: SYNOPSIS: Use 'noreturn' in prototypes
  setjmp.3: SYNOPSIS: Use 'noreturn' in prototypes

 man2/_exit.2        | 4 ++--
 man3/abort.3        | 2 +-
 man3/err.3          | 8 ++++----
 man3/exit.3         | 2 +-
 man3/pthread_exit.3 | 2 +-
 man3/setjmp.3       | 4 ++--
 6 files changed, 11 insertions(+), 11 deletions(-)

-- 
2.30.1.721.g45526154a5

[PATCH 1/6] abort.3: SYNOPSIS: Use 'noreturn' in prototypes

[Alejandro Colomar]

POSIX specifies that abort() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/abort.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/abort.3 b/man3/abort.3
index 71d555841..b33d23ad1 100644
--- a/man3/abort.3
+++ b/man3/abort.3
@@ -38,7 +38,7 @@ abort \- cause abnormal process termination
 .nf
 .B #include <stdlib.h>
 .PP
-.B void abort(void);
+.B noreturn void abort(void);
 .fi
 .SH DESCRIPTION
 The
-- 
2.30.1.721.g45526154a5

[PATCH 2/6] _exit.2: SYNOPSIS: Use 'noreturn' in prototypes

[Alejandro Colomar]

POSIX specifies that _exit() and _Exit() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.

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

diff --git a/man2/_exit.2 b/man2/_exit.2
index fe43f47ce..6e8e77a84 100644
--- a/man2/_exit.2
+++ b/man2/_exit.2
@@ -33,11 +33,11 @@ _exit, _Exit \- terminate the calling process
 .nf
 .B #include <unistd.h>
 .PP
-.BI "void _exit(int " status );
+.BI "noreturn void _exit(int " status );
 .PP
 .B #include <stdlib.h>
 .PP
-.BI "void _Exit(int " status );
+.BI "noreturn void _Exit(int " status );
 .fi
 .PP
 .RS -4
-- 
2.30.1.721.g45526154a5

[PATCH 3/6] err.3: SYNOPSIS: Use 'noreturn' in prototypes

[Alejandro Colomar]

Glibc uses __attribute__((__noreturn__)) for [v]err[x]().
These functions never return.
Let's use standard C11 'noreturn' in the manual page.

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

diff --git a/man3/err.3 b/man3/err.3
index 128afde6a..a4d4eb620 100644
--- a/man3/err.3
+++ b/man3/err.3
@@ -43,16 +43,16 @@ err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
 .nf
 .B #include <err.h>
 .PP
-.BI "void err(int " eval ", const char *" fmt ", ...);"
-.BI "void errx(int " eval ", const char *" fmt ", ...);"
+.BI "noreturn void err(int " eval ", const char *" fmt ", ...);"
+.BI "noreturn void errx(int " eval ", const char *" fmt ", ...);"
 .PP
 .BI "void warn(const char *" fmt ", ...);"
 .BI "void warnx(const char *" fmt ", ...);"
 .PP
 .B #include <stdarg.h>
 .PP
-.BI "void verr(int " eval ", const char *" fmt ", va_list " args );
-.BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
+.BI "noreturn void verr(int " eval ", const char *" fmt ", va_list " args );
+.BI "noreturn void verrx(int " eval ", const char *" fmt ", va_list " args );
 .PP
 .BI "void vwarn(const char *" fmt ", va_list " args );
 .BI "void vwarnx(const char *" fmt ", va_list " args );
-- 
2.30.1.721.g45526154a5

[PATCH 4/6] exit.3: SYNOPSIS: Use 'noreturn' in prototypes

[Alejandro Colomar]

POSIX specifies that exit() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/exit.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/exit.3 b/man3/exit.3
index 50eec7821..3e38a32a6 100644
--- a/man3/exit.3
+++ b/man3/exit.3
@@ -33,7 +33,7 @@ exit \- cause normal process termination
 .nf
 .B #include <stdlib.h>
 .PP
-.BI "void exit(int " status );
+.BI "noreturn void exit(int " status );
 .fi
 .SH DESCRIPTION
 The
-- 
2.30.1.721.g45526154a5

[PATCH 5/6] pthread_exit.3: SYNOPSIS: Use 'noreturn' in prototypes

[Alejandro Colomar]

POSIX specifies that pthread_exit() shall not return.
Glibc uses __attribute__((__noreturn__)).
Let's use standard C11 'noreturn' in the manual page.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/pthread_exit.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/pthread_exit.3 b/man3/pthread_exit.3
index 60879f07c..de9f9abcf 100644
--- a/man3/pthread_exit.3
+++ b/man3/pthread_exit.3
@@ -30,7 +30,7 @@ pthread_exit \- terminate calling thread
 .nf
 .B #include <pthread.h>
 .PP
-.BI "void pthread_exit(void *" retval );
+.BI "noreturn void pthread_exit(void *" retval );
 .PP
 Compile and link with \fI\-pthread\fP.
 .fi
-- 
2.30.1.721.g45526154a5

[PATCH 6/6] setjmp.3: SYNOPSIS: Use 'noreturn' in prototypes

[Alejandro Colomar]

POSIX specifies that [sig]longjmp() shall not return,
transferring control back to the caller of [sig]setjmp().
Glibc uses __attribute__((__noreturn__)) for [sig]longjmp().
Let's use standard C11 'noreturn' in the manual page.

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

diff --git a/man3/setjmp.3 b/man3/setjmp.3
index 7c52f4bea..d9b011b46 100644
--- a/man3/setjmp.3
+++ b/man3/setjmp.3
@@ -31,8 +31,8 @@ setjmp, sigsetjmp, longjmp, siglongjmp  \- performing a nonlocal goto
 .BI "int setjmp(jmp_buf " env );
 .BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs );
 .PP
-.BI "void longjmp(jmp_buf " env ", int " val );
-.BI "void siglongjmp(sigjmp_buf " env ", int " val );
+.BI "noreturn void longjmp(jmp_buf " env ", int " val );
+.BI "noreturn void siglongjmp(sigjmp_buf " env ", int " val );
 .fi
 .PP
 .RS -4
-- 
2.30.1.721.g45526154a5

Re: [PATCH 1/6] abort.3: SYNOPSIS: Use 'noreturn' in prototypes

[Michael Kerrisk (man-pages)]

Hi Alex,

On 2/18/21 10:23 PM, Alejandro Colomar wrote:
> POSIX specifies that abort() shall not return.
> Glibc uses __attribute__((__noreturn__)).
> Let's use standard C11 'noreturn' in the manual page.

C11!? I'm only just getting over C99... But okay, it seems
reasonable :-). I applied all of the patches.

Cheers,

Michael
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man3/abort.3 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man3/abort.3 b/man3/abort.3
> index 71d555841..b33d23ad1 100644
> --- a/man3/abort.3
> +++ b/man3/abort.3
> @@ -38,7 +38,7 @@ abort \- cause abnormal process termination
>  .nf
>  .B #include <stdlib.h>
>  .PP
> -.B void abort(void);
> +.B noreturn void abort(void);
>  .fi
>  .SH DESCRIPTION
>  The
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/