Skip to contentSkip to conversation

psiginfo.3, psignal.3: Document psiginfo()

PATCH Applied Guillem Jover 2 participants 5 messages Oct 6, 2010 – Oct 18, 2010 3 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 psiginfo.3, psignal.3: Document psiginfo()

---
 man3/psiginfo.3 |    1 +
 man3/psignal.3  |   28 ++++++++++++++++++++--------
 2 files changed, 21 insertions(+), 8 deletions(-)
 create mode 100644 man3/psiginfo.3
man3/psiginfo.3 new file +1 -0
new file mode 100644
index 0000000..cd748fa
@@ -0,0 +1 @@
+.so man3/psignal.3
man3/psignal.3 +20 -8
index 128fe8f..729acc9 100644
@@ -25,16 +25,15 @@
 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
 .\"     386BSD man pages
 .\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith ([email protected])
-.\" FIXME glibc 2.10 adds psiginfo(), specified in SUSv4.  This function
-.\" should be documented, probably on this page.
-.TH PSIGNAL 3  2008-08-21 "GNU" "Linux Programmer's Manual"
+.TH PSIGNAL 3  2010-10-06 "GNU" "Linux Programmer's Manual"
 .SH NAME
-psignal \- print signal message
+psignal, psiginfo \- print signal message
 .SH SYNOPSIS
 .nf
 .B #include <signal.h>
 .sp
 .BI "void psignal(int " sig ", const char *" s );
+.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s );
 .sp
 .BI "extern const char *const " sys_siglist [];
 .fi
@@ -47,23 +46,36 @@ Feature Test Macro Requirements for glibc (see
 .BR psignal ():
 _SVID_SOURCE || _BSD_SOURCE
 .br
+.BR psiginfo ():
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.br
 .IR sys_siglist :
 _BSD_SOURCE
 .SH DESCRIPTION
 The
 .BR psignal ()
-function displays a message on \fIstderr\fP
+and
+.BR psiginfo ()
+functions display a message on \fIstderr\fP
 consisting of the string \fIs\fP, a colon, a space, and a string
-describing the signal number \fIsig\fP.
-If \fIsig\fP is invalid,
+describing the signal number \fIsig\fP or signal information \fIpinfo\fP.
+If the string \fIs\fP is NULL or empty, the colon and space are omitted.
+For
+.BR psignal ()
+if \fIsig\fP is invalid,
 the message displayed will indicate an unknown signal.
+For
+.BR psiginfo (),
+\fIpinfo\fP should point to a valid \fIsiginfo_t\fP structure.
 .PP
 The array \fIsys_siglist\fP holds the signal description strings
 indexed by signal number.
 .SH "RETURN VALUE"
 The
 .BR psignal ()
-function returns no value.
+and
+.BR psiginfo ()
+functions return no value.
 .SH "CONFORMING TO"
 POSIX.1-2008, 4.3BSD.
 .SH "SEE ALSO"
Signature · 6 lines
1.7.2.3

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20101006065142.GA26673-v62vTE6/wQGgM1MOaoewpti2O/[email protected]

#2 lore raw
Quoted 76 lines · Guillem Jover

---
 man3/psiginfo.3 |    1 +
 man3/psignal.3  |   28 ++++++++++++++++++++--------

 2 files changed, 21 insertions(+), 8 deletions(-)

 create mode 100644 man3/psiginfo.3

man3/psiginfo.3 new file +1 -0
new file mode 100644
index 0000000..cd748fa
@@ -0,0 +1 @@
+.so man3/psignal.3
man3/psignal.3 +0 -0
index 128fe8f..729acc9 100644
@@ -25,16 +25,15 @@
  .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)

 .\"     386BSD man pages
 .\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith ([email protected]) -.\" FIXME glibc 2.10 adds psiginfo(), specified in SUSv4.  This function -.\" should be documented, probably on this page.
-.TH PSIGNAL 3  2008-08-21 "GNU" "Linux Programmer's Manual"
+.TH PSIGNAL 3  2010-10-06 "GNU" "Linux Programmer's Manual"
 .SH NAME

man3/psignal.3 +1 -1
-psignal \- print signal message
+psignal, psiginfo \- print signal message

 .SH SYNOPSIS
 .nf
 .B #include <signal.h>
 .sp
 .BI "void psignal(int " sig ", const char *" s );
+.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s ); .sp
 .BI "extern const char *const " sys_siglist [];
 .fi

man3/psignal.3 +0 -0
@@ -47,23 +46,36 @@ Feature Test Macro Requirements for glibc (see

 .BR psignal ():
 _SVID_SOURCE || _BSD_SOURCE
 .br
+.BR psiginfo ():
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L +.br
 .IR sys_siglist :
 _BSD_SOURCE
 .SH DESCRIPTION
 The
 .BR psignal ()

man3/psignal.3 +3 -1
-function displays a message on \fIstderr\fP
+and
+.BR psiginfo ()
+functions display a message on \fIstderr\fP

 consisting of the string \fIs\fP, a colon, a space, and a string

man3/psignal.3 +5 -2
-describing the signal number \fIsig\fP.
-If \fIsig\fP is invalid,
+describing the signal number \fIsig\fP or signal information \fIpinfo\fP.
+If the string \fIs\fP is NULL or empty, the colon and space are omitted.
+For
+.BR psignal ()
+if \fIsig\fP is invalid,

 the message displayed will indicate an unknown signal. +For
+.BR psiginfo (),
+\fIpinfo\fP should point to a valid \fIsiginfo_t\fP structure. .PP
 The array \fIsys_siglist\fP holds the signal description strings indexed by signal number.
 .SH "RETURN VALUE"
 The
 .BR psignal ()

man3/psignal.3 +3 -1
-function returns no value.
+and
+.BR psiginfo ()
+functions return no value.
Quoted 5 lines

 .SH "CONFORMING TO"
 POSIX.1-2008, 4.3BSD.
 .SH "SEE ALSO"
--
1.7.2.3

Guillem,

Thanks for this patch. I'd like to have more detail about what psiginfo() displays, though I appreciate that it is difficult to describe this compactly. Also there seem to be bugs in the interface. I filed the following:
http://sourceware.org/bugzilla/show_bug.cgi?id=12107
http://sourceware.org/bugzilla/show_bug.cgi?id=12108
Do these also look like problems to you?

Cheers,

Michael

Signature · 7 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): AANLkTi=WhRscu96fioF0jvfp2a874gtA=niw-DDx8NC--JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#4 lore raw

Hello Guillem,

I applied the slightly modified version of your patch below. Thanks!

Cheers,

Michael--- a/man3/psignal.3
+++ b/man3/psignal.3
@@ -25,16 +25,15 @@
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith ([email protected])
-.\" FIXME glibc 2.10 adds psiginfo(), specified in SUSv4. This function
-.\" should be documented, probably on this page.
-.TH PSIGNAL 3 2008-08-21 "GNU" "Linux Programmer's Manual"
+.TH PSIGNAL 3 2010-10-06 "GNU" "Linux Programmer's Manual"
.SH NAME
-psignal \- print signal message
+psignal, psiginfo \- print signal message
.SH SYNOPSIS
.nf
.B #include <signal.h>
.sp
.BI "void psignal(int " sig ", const char *" s );
+.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s );
.sp
.BI "extern const char *const " sys_siglist [];
.fi
@@ -47,23 +46,39 @@ Feature Test Macro Requirements for glibc (see
.BR psignal ():
_SVID_SOURCE || _BSD_SOURCE
.br
+.BR psiginfo ():
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.br
.IR sys_siglist :
_BSD_SOURCE
.SH DESCRIPTION
The
.BR psignal ()
function displays a message on \fIstderr\fP
-consisting of the string \fIs\fP, a colon, a space, and a string
-describing the signal number \fIsig\fP.
+consisting of the string \fIs\fP, a colon, a space, a string
+describing the signal number \fIsig\fP, and a trailing newline.
+If the string \fIs\fP is NULL or empty, the colon and space are omitted.
If \fIsig\fP is invalid,
the message displayed will indicate an unknown signal.
-.PP
+
+The
+.BR psiginfo ()
+function is like
+.BR psignal (),
+except that it displays information about the signal described by
+.IR pinfo ,
+which should point to a valid
+.I siginfo_t
+structure.
+
The array \fIsys_siglist\fP holds the signal description strings
indexed by signal number.
.SH "RETURN VALUE"
The
.BR psignal ()
-function returns no value.
+and
+.BR psiginfo ()
+functions return no value.
.SH "CONFORMING TO"
POSIX.1-2008, 4.3BSD.
.SH "SEE ALSO"
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): AANLkTim==RDg8a8eVYT1Dd=RRe2HKVaffW178opoycwe-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#6 lore raw

Hi Guillem,

I also added some details for psiginfo().

thanks,

Michael

man3/psignal.3 +0 -0
@@ -70,6 +70,17 @@ except that it displays information about the

signal described by
which should point to a valid
.I siginfo_t
structure.
+As well as the signal description,
+.BR psiginfo ()
+displays information about the origin of the signal, +and other information relevant to the signal
+(e.g., the relevant memory address for hardware-generated signals, +the child process ID for
+.BR SIGCHLD ,
+and the user ID and process ID of the sender, for signals set using +.BR kill (2)
+or
+.BR sigqueue (2)).

The array \fIsys_siglist\fP holds the signal description strings indexed by signal number.
@@ -79,8 +90,22 @@ The
and
.BR psiginfo ()
functions return no value.
+.SH VERSIONS
+The
+.BR psiginfo()
+function was added to glibc in version 2.10.
.SH "CONFORMING TO"
POSIX.1-2008, 4.3BSD.
+.SH BUGS
+As at glibc 2.12,
+.BR psiginfo ()
+has the following bugs:
+.IP * 3
+In some circumstances, a trailing newline is not printed. +.\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=12107
+.IP *
+Additional details for are not displayed for realtime signals. +.\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=12108
.SH "SEE ALSO"
.BR sigaction (2),
.BR perror (3),

Signature · 7 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
#7 lore raw
In reply to a message not in the archive
Quoted 3 lines · Michael Kerrisk

Thanks for this patch. I'd like to have more detail about what psiginfo() displays, though I appreciate that it is difficult to describe this compactly.

The amendments and additions you did look very good, thanks for that. I'll try to split the changes as you did in the future.

Quoted 5 lines

Also there seem to be bugs in the interface.
I filed the following:
http://sourceware.org/bugzilla/show_bug.cgi?id=12107
http://sourceware.org/bugzilla/show_bug.cgi?id=12108
Do these also look like problems to you?

Yes.

regards,
guillem
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html