psiginfo.3, psignal.3: Document psiginfo()
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
@@ -0,0 +1 @@ +.so man3/psignal.3
man3/psignal.3 +20 -8
@@ -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]
Quoted 76 lines · Guillem Jover
Signed-off-by Guillem Jover <[email protected]>---
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@@ -0,0 +1 @@ +.so man3/psignal.3man3/psignal.3 +0
-0@@ -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 addspsiginfo(), 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 NAMEman3/psignal.3 +1
-1-psignal \- print signal message +psignal, psiginfo \- print signal message.SH SYNOPSIS
.nf
.B #include <signal.h>
.sp
.BI "voidpsignal(int " sig ", const char *" s );
+.BI "voidpsiginfo(const siginfo_t *" pinfo ", const char *" s ); .sp
.BI "extern const char *const "sys_siglist[];
.fiman3/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
.IRsys_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\fPconsisting 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
Michael Kerrisk
AppliedHello 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
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
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