For review: mtrace(1) man page

For review: mtrace(1) man page

[Jan Chaloupka]

mtrace(1) command is not documented. All informations come from the script.

Feel free to comment or ask any question.

Thank you
Jan

.\" Copyright (c) 2013, Peter Schiffer (pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org)
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.TH MTRACE 1 2013-04-10 "GNU glibc 2.18" "Memory diagnostic tools"
.SH NAME
mtrace \- interpret the malloc trace log
.SH SYNOPSIS
.BR mtrace " [\fIOPTION\fR]... [\fIBINARY\fR] \fIMTRACEDATA\fR"
.SH DESCRIPTION
.B mtrace
is a Perl script used to interpret and provide human readable output
of the trace log created by
.BR mtrace (3)
function stored in the
.B MTRACEDATA
file.
If
.B BINARY
is provided, output of
.B mtrace
also contains source file name with line number information
of problem location
(assuming that
.B BINARY
was compiled with debugging information).

For more information about
.BR mtrace (3)
function and
.B mtrace
script usage, refer to the
.BR mtrace (3)
manual page.
.SH OPTIONS
.TP
.BI \fB\-\-help
Print help and exit.
.TP
.BI \fB\-\-version
Print version information and exit.
.SH BUGS
For bug reporting instructions, please see:
<http://www.gnu.org/software/libc/bugs.html>.
.SH SEE ALSO
.BR mtrace (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: For review: mtrace(1) man page

[Jan Chaloupka]

Hi Tushar,

On 07/22/2014 09:45 AM, Tushar Shinde wrote:
> Hi Jan,
>
> Is  this MTRACEDATA is same as environment  variable  MALLOC_TRACE 
> of MTRACE(3) ?
> If yes we should keep MALLOC_TRACE instead of MTRACEDATA to avoid 
> confusion.
>
> Tushar

thank you for noticing. Those are script arguments, not environment 
variables. Changed bold into underline.

.\" Copyright (c) 2013, Peter Schiffer (pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org)
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.TH MTRACE 1 2013-04-10 "GNU glibc 2.18" "Memory diagnostic tools"
.SH NAME
mtrace \- interpret the malloc trace log
.SH SYNOPSIS
.BR mtrace " [\fIOPTION\fR]... [\fIBINARY\fR] \fIMTRACEDATA\fR"
.SH DESCRIPTION
.B mtrace
is a Perl script used to interpret and provide human readable output
of the trace log created by
.BR mtrace (3)
function stored in the
\fIMTRACEDATA\fR
file.
If
\fIBINARY\fR
is provided, output of
.B mtrace
also contains source file name with line number information
of problem location
(assuming that
\fIBINARY\fR
was compiled with debugging information).

For more information about
.BR mtrace (3)
function and
.B mtrace
script usage, refer to the
.BR mtrace (3)
manual page.
.SH OPTIONS
.TP
.BI \fB\-\-help
Print help and exit.
.TP
.BI \fB\-\-version
Print version information and exit.
.SH BUGS
For bug reporting instructions, please see:
<http://www.gnu.org/software/libc/bugs.html>.
.SH SEE ALSO
.BR mtrace (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: For review: mtrace(1) man page

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 674 bytes --]

On Fri 18 Jul 2014 11:01:02 Jan Chaloupka wrote:
> mtrace(1) command is not documented. All informations come from the script.
> 
> Feel free to comment or ask any question.

it doesn't feel right for truly glibc-specific tools to have their man pages 
hosted in the Linux man-pages project, especially when you consider 
functionality/flags/etc... skew across glibc versions trying to be tracked in 
an unrelated git repo.

the GNU standard doesn't say that we can't include them in GNU projects, just 
that they should be secondary to info pages.  so i think things like mtrace(1) 
are better in glibc itself.

how else do people feel in this regard ?
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: For review: mtrace(1) man page

[Jan Chaloupka]

Hi, Mike

On 08/02/2014 06:57 PM, Mike Frysinger wrote:
> On Fri 18 Jul 2014 11:01:02 Jan Chaloupka wrote:
>> mtrace(1) command is not documented. All informations come from the script.
>>
>> Feel free to comment or ask any question.
> it doesn't feel right for truly glibc-specific tools to have their man pages
> hosted in the Linux man-pages project, especially when you consider
> functionality/flags/etc... skew across glibc versions trying to be tracked in
> an unrelated git repo.

First thing I do, when I need help, is to look into man page. Why? it is 
fast.

> the GNU standard doesn't say that we can't include them in GNU projects, just
> that they should be secondary to info pages.  so i think things like mtrace(1)
> are better in glibc itself.

I have nothing againts putting it into glibc itself as well.

> how else do people feel in this regard ?
> -mike

Jan
--
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: For review: mtrace(1) man page

[Michael Kerrisk (man-pages)]

On 08/02/2014 11:57 AM, Mike Frysinger wrote:
> On Fri 18 Jul 2014 11:01:02 Jan Chaloupka wrote:
>> mtrace(1) command is not documented. All informations come from the script.
>>
>> Feel free to comment or ask any question.
> 
> it doesn't feel right for truly glibc-specific tools to have their man pages 
> hosted in the Linux man-pages project, especially when you consider 
> functionality/flags/etc... skew across glibc versions trying to be tracked in 
> an unrelated git repo.

Well, from a man-pages perspective, this doesn't seem terribly different from
the Section 3 APIs. Also, a number of glibc commands are already (in many cases,
since long ago) documented in man1 and man8.

Cheers,

Michael



> the GNU standard doesn't say that we can't include them in GNU projects, just 
> that they should be secondary to info pages.  so i think things like mtrace(1) 
> are better in glibc itself.
> 
> how else do people feel in this regard ?
> -mike
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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: For review: mtrace(1) man page

[Michael Kerrisk (man-pages)]

Hello Jan,

I've merged this page. Thank you for submitting it on Peter's behalf.

Cheers,

Michael


On 07/22/2014 10:17 AM, Jan Chaloupka wrote:
> Hi Tushar,
> 
> On 07/22/2014 09:45 AM, Tushar Shinde wrote:
>> Hi Jan,
>>
>> Is  this MTRACEDATA is same as environment  variable  MALLOC_TRACE 
>> of MTRACE(3) ?
>> If yes we should keep MALLOC_TRACE instead of MTRACEDATA to avoid 
>> confusion.
>>
>> Tushar
> 
> thank you for noticing. Those are script arguments, not environment 
> variables. Changed bold into underline.
> 
> .\" Copyright (c) 2013, Peter Schiffer (pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org)
> .\"
> .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual; if not, see
> .\" <http://www.gnu.org/licenses/>.
> .\" %%%LICENSE_END
> .TH MTRACE 1 2013-04-10 "GNU glibc 2.18" "Memory diagnostic tools"
> .SH NAME
> mtrace \- interpret the malloc trace log
> .SH SYNOPSIS
> .BR mtrace " [\fIOPTION\fR]... [\fIBINARY\fR] \fIMTRACEDATA\fR"
> .SH DESCRIPTION
> .B mtrace
> is a Perl script used to interpret and provide human readable output
> of the trace log created by
> .BR mtrace (3)
> function stored in the
> \fIMTRACEDATA\fR
> file.
> If
> \fIBINARY\fR
> is provided, output of
> .B mtrace
> also contains source file name with line number information
> of problem location
> (assuming that
> \fIBINARY\fR
> was compiled with debugging information).
> 
> For more information about
> .BR mtrace (3)
> function and
> .B mtrace
> script usage, refer to the
> .BR mtrace (3)
> manual page.
> .SH OPTIONS
> .TP
> .BI \fB\-\-help
> Print help and exit.
> .TP
> .BI \fB\-\-version
> Print version information and exit.
> .SH BUGS
> For bug reporting instructions, please see:
> <http://www.gnu.org/software/libc/bugs.html>.
> .SH SEE ALSO
> .BR mtrace (3)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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