[PATCH] psiginfo.3, psignal.3: Document psiginfo()

[PATCH] psiginfo.3, psignal.3: Document psiginfo()

[Guillem Jover]

Signed-off-by: Guillem Jover <guillem-+FW4gsLVM0RAfugRpC6u6w@public.gmane.org>
---
 man3/psiginfo.3 |    1 +
 man3/psignal.3  |   28 ++++++++++++++++++++--------
 2 files changed, 21 insertions(+), 8 deletions(-)
 create mode 100644 man3/psiginfo.3

diff --git a/man3/psiginfo.3 b/man3/psiginfo.3
new file mode 100644
index 0000000..cd748fa
--- /dev/null
+++ b/man3/psiginfo.3
@@ -0,0 +1 @@
+.so man3/psignal.3
diff --git a/man3/psignal.3 b/man3/psignal.3
index 128fe8f..729acc9 100644
--- 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 (faith-+5Oa3zvhR2o3uPMLIKxrzw@public.gmane.org)
-.\" 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"
-- 
1.7.2.3

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] psiginfo.3, psignal.3: Document psiginfo()

[Michael Kerrisk]

On Wed, Oct 6, 2010 at 8:51 AM, Guillem Jover <guillem-+FW4gsLVM0RAfugRpC6u6w@public.gmane.org> wrote:
> Signed-off-by: Guillem Jover <guillem-+FW4gsLVM0RAfugRpC6u6w@public.gmane.org>
> ---
>  man3/psiginfo.3 |    1 +
>  man3/psignal.3  |   28 ++++++++++++++++++++--------
>  2 files changed, 21 insertions(+), 8 deletions(-)
>  create mode 100644 man3/psiginfo.3
>
> diff --git a/man3/psiginfo.3 b/man3/psiginfo.3
> new file mode 100644
> index 0000000..cd748fa
> --- /dev/null
> +++ b/man3/psiginfo.3
> @@ -0,0 +1 @@
> +.so man3/psignal.3
> diff --git a/man3/psignal.3 b/man3/psignal.3
> index 128fe8f..729acc9 100644
> --- 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 (faith-+5Oa3zvhR2o@public.gmane.orgdu)
> -.\" 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"
> --
> 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

-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] psiginfo.3, psignal.3: Document psiginfo()

[Michael Kerrisk]

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 (faith-+5Oa3zvhR2o3uPMLIKxrzw@public.gmane.org)
-.\" 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] psiginfo.3, psignal.3: Document psiginfo()

[Michael Kerrisk]

Hi Guillem,

I also added some details for psiginfo().

thanks,

Michael


--- a/man3/psignal.3
+++ b/man3/psignal.3
@@ -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),

-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] psiginfo.3, psignal.3: Document psiginfo()

[Guillem Jover]

On Sun, 2010-10-10 at 17:22:57 +0200, Michael Kerrisk wrote:
> 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.

> 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html