Skip to contentSkip to conversation

man[23]: SYNOPSIS: Use 'noreturn' in prototypes.

PATCH In review Alejandro Colomar 2 participants 8 messages Feb 18, 2021 – Feb 19, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

cover man[23]: SYNOPSIS: Use 'noreturn' in prototypes.

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(-)
Signature · 1 line
2.30.1.721.g45526154a5
#1 lore raw

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

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

---
 man3/abort.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man3/abort.3 +1 -1
index 71d555841..b33d23ad1 100644
@@ -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
Signature · 1 line
2.30.1.721.g45526154a5
#2 lore raw

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

Hi Alex,

Quoted 3 lines · Alejandro Colomar

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

Quoted 20 lines
---
 man3/abort.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man3/abort.3 +1 -1
index 71d555841..b33d23ad1 100644
@@ -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
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/
#3 lore raw

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

In reply to 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.

---
 man2/_exit.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
man2/_exit.2 +2 -2
index fe43f47ce..6e8e77a84 100644
@@ -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
Signature · 1 line
2.30.1.721.g45526154a5
#4 lore raw

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

In reply to Alejandro Colomar

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

---
 man3/err.3 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
man3/err.3 +4 -4
index 128afde6a..a4d4eb620 100644
@@ -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 );
Signature · 1 line
2.30.1.721.g45526154a5
#5 lore raw

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

In reply to Alejandro Colomar

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

---
 man3/exit.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man3/exit.3 +1 -1
index 50eec7821..3e38a32a6 100644
@@ -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
Signature · 1 line
2.30.1.721.g45526154a5
#6 lore raw

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

In reply to Alejandro Colomar

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

---
 man3/pthread_exit.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man3/pthread_exit.3 +1 -1
index 60879f07c..de9f9abcf 100644
@@ -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
Signature · 1 line
2.30.1.721.g45526154a5
#7 lore raw

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

In reply to 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.

---
 man3/setjmp.3 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
man3/setjmp.3 +2 -2
index 7c52f4bea..d9b011b46 100644
@@ -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
Signature · 1 line
2.30.1.721.g45526154a5