Add strace-log-merge man page

* strace-log-merge.1.in: New file.
* NEWS: Mention this.
* .gitignore: Add strace-log-merge.1.
* Makefile.am (man_MANS): Likewise.
* configure.ac (AC_CONFIG_FILES): Likewise.
* debian/strace.manpages: Likewise.

.gitignore

@@ -57,6 +57,7 @@
 /strace-*.tar.gz
 /strace-*.tar.xz
 /strace.1
+/strace-log-merge.1
 /strace.dsc
 /strace.spec
 /sys_func.h

Makefile.am

@@ -38,7 +38,7 @@ endif
 SUBDIRS = . tests $(TESTS_M32) $(TESTS_MX32)
 
 bin_PROGRAMS = strace
-man_MANS = strace.1
+man_MANS = strace.1 strace-log-merge.1
 bin_SCRIPTS = strace-graph strace-log-merge
 
 OS		= linux

NEWS

@@ -11,6 +11,7 @@ Noteworthy changes in release ?.?? (????-??-??)
     level.
   * Enhanced decoding of BPF_MAP_CREATE command of bpf syscall.
   * Updated lists of MSG_* and SHM_* constants.
+  * Added manual page for the strace-log-merge command.
 
 * Bug fixes
   * Fixed multi-personality support in cross builds.

configure.ac

@@ -896,6 +896,7 @@ AC_CONFIG_FILES([Makefile
 		 tests-m32/Makefile
 		 tests-mx32/Makefile
 		 strace.1
+		 strace-log-merge.1
 		 strace.spec
 		 debian/changelog])
 AC_OUTPUT

debian/strace.manpages

@@ -1 +1,2 @@
 strace.1
+strace-log-merge.1

strace-log-merge.1.in

@@ -0,0 +1,146 @@
+.\" Copyright (c) 2017 The strace developers.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" Required option.
+.de OR
+.  ie \\n(.$-1 \
+.    RI "\fB\\$1\fP" "\ \\$2"
+.  el \
+.    BR "\\$1"
+..
+.\"
+.TH STRACE-LOG-MERGE 1 "@MANPAGE_DATE@" "strace @VERSION@"
+.\"
+.SH NAME
+strace-log-merge \- merge strace \-ff \-tt output
+.\"
+.SH SYNOPSIS
+.SY strace\-log\-merge
+.IR STRACE_LOG
+.YS
+.SY strace\-log\-merge
+.OR \-\-help
+.YS
+.\"
+.SH DESCRIPTION
+.B strace\-log\-merge
+merges the output of
+.B strace \-ff \-tt[t]
+command, prepending PID to each line and sorting the result using time stamp as
+a key.
+.\"
+.SH OPTIONS
+.\"
+.TP
+.B \-\-help
+Show program usage and exit.
+.TP
+.I STRACE_LOG
+Output file name prefix of files produced by a
+.B strace -ff -tt[t]
+command.
+.SH EXIT STATUS
+.TP
+.B 0
+Success
+.TP
+.B Non-zero
+Error occurred: either no argument specified (in that case a usage is printed),
+or something went wrong during the processing of
+.IR STRACE_LOG ".*"
+files.
+.\"
+.SH USAGE EXAMPLE
+.sp
+.nf
+.ft CW
+$ strace -o sleepy -ff -tt -e trace=execve,nanosleep \\
+        sh -c 'sleep 0.1 & sleep 0.2 & sleep 0.3'
+$ strace-log-merge sleepy | fold -w 72 -s
+13475 21:13:52.040837 execve("/bin/sh", ["sh", "-c", "sleep 0.1 & sleep
+0.2 & sleep 0."...], 0x7ffde54b2450 /* 33 vars */) = 0
+13478 21:13:52.044050 execve("/bin/sleep", ["sleep", "0.3"],
+0x5631be4f87a8 /* 33 vars */) = 0
+13476 21:13:52.044269 execve("/bin/sleep", ["sleep", "0.1"],
+0x5631be4f87a8 /* 33 vars */) = 0
+13477 21:13:52.044389 execve("/bin/sleep", ["sleep", "0.2"],
+0x5631be4f87a8 /* 33 vars */) = 0
+13478 21:13:52.046207 nanosleep({tv_sec=0, tv_nsec=300000000}, NULL) = 0
+13476 21:13:52.046303 nanosleep({tv_sec=0, tv_nsec=100000000}, NULL) = 0
+13477 21:13:52.046318 nanosleep({tv_sec=0, tv_nsec=200000000}, NULL) = 0
+13476 21:13:52.146852 +++ exited with 0 +++
+13475 21:13:52.146942 --- SIGCHLD {si_signo=SIGCHLD,
+si_code=CLD_EXITED, si_pid=13476, si_uid=1000, si_status=0, si_utime=0,
+si_stime=0} ---
+13477 21:13:52.247782 +++ exited with 0 +++
+13475 21:13:52.247885 --- SIGCHLD {si_signo=SIGCHLD,
+si_code=CLD_EXITED, si_pid=13477, si_uid=1000, si_status=0, si_utime=0,
+si_stime=0} ---
+13478 21:13:52.347680 +++ exited with 0 +++
+13475 21:13:52.347786 --- SIGCHLD {si_signo=SIGCHLD,
+si_code=CLD_EXITED, si_pid=13478, si_uid=1000, si_status=0, si_utime=0,
+si_stime=0} ---
+13475 21:13:52.348069 +++ exited with 0 +++
+.ft R
+.fi
+.sp
+.\"
+.SH NOTES
+.I strace-log-merge
+does not work well with
+.B strace
+logs generated by
+.B strace -tt
+invocation that pass midnight, as those lack the information required
+for the proper sorting.
+Employing the
+.B -ttt
+option in the respective
+.B strace
+invocation should solve the problem.
+.\"
+.SH BUGS
+.I strace-log-merge
+does not perform any checks whether the files specified are in the correct
+format and implies that only files from a single
+.I strace
+session match
+.IR STRACE_LOG ".*"
+glob pattern.
+.\"
+.SH HISTORY
+The initial version of
+.I strace-log-merge
+was written by Denys Vlasenko in 2012.
+.\"
+.SH REPORTING BUGS
+Problems with
+.B strace-log-merge
+should be reported to the
+.B strace
+mailing list at <strace\-devel@lists.sourceforge.net>.
+.\"
+.SH "SEE ALSO"
+.BR strace (1)