writecoredump.man

能把所有线程的数据和环境记录到文件,方便调试.

'\" t
.TH WRITECOREDUMP 3 "Feb 15, 2007"
.SH NAME
WriteCoreDump, WriteCoreDumpLimited, WriteCompressedCoreDump \- writes
a snapshot of the current process
.SH SYNOPSIS
.ad l
.PP
.B "#include \*(lqgoogle/coredumper.h\*(rq"
.PP
.BI int\~WriteCoreDump(const\~char\~* file_name );
.PP
.BI int\~WriteCoreDumpLimited(const\~char\ \:* file_name ,\ \:size_t\~ \
    \:max_length );
.HP 28
.BI int\~Write\%Compressed\%Core\%Dump(const\~char\ \:* file_name \
    ,\ \:size_t\ \: max_length ,\ \:const\~struct\~Coredumper\%Compressor\ \
    \:compressors [],\ \:struct\~Coredumper\%Compressor\ \:** \
    selected_compressor );
.PP
.ad b
.SH DESCRIPTION
The \fBWriteCoreDump\fP() function writes a core file to
.IR file_name .
The calling process continues running after the file has been
written.
.PP
The \fBWriteCoreDumpLimited\fP() function restricts the maximum length
of the written file. This is similar to what setting calling
.BR setrlimit (2)
does for system-generated core files.
.PP
The \fBWriteCompressedCoreDump\fP() function attempts to compress the
core file on the fly, if a suitable
.I compressor
could be located.
.PP
If
.IR selected_compressor
is non-NULL, it will be set to the actual
.I CoredumperCompressor
object used.
.PP
The
.I filename
automatically has a suitable suffix appended to it. Normally this
would be \*(lq.bz2\*(rq for
.BR bzip2 (1)
compression, \*(lq.gz\*(rq for
.BR gzip (1)
compression, or \*(lq.Z\*(rq for
.BR compress (1)
compression. This behavior can be changed by defining custom
.I CoredumperCompressor
descriptions. See the manual page for
.BR GetCoreDump (3)
for more details.
.SH RETURN VALUE
\fBWriteCoreDump\fP(), \fBWriteCoreDumpLimited\fP(), and
\fBWriteCompressedCoreDump\fP() return zero on success and \-1 on
failure. In case of failure,
.I errno
will be set appropriately.
.SH ERRORS
The most common reason for failure is for another process to already
use the debugging API that is needed to generate the core
files. This could, for instance, be
.BR gdb (1),
or
.BR strace(1).
.SH NOTES
The coredumper functions momentarily suspend all threads, while
creating a COW (copy-on-write) copy of the process's address space.
.PP
The functions are neither reentrant nor async signal safe. Callers
should wrap a mutex around their invocation, if necessary.
.PP
The current implementation tries very hard to behave reasonably when
called from a signal handler, but no guarantees are made that this
will always work. Most importantly, it is the caller's responsibility
to make sure that there are never more than one instance of functions
from the \fBGetCoreDump\fP() or \fBWriteCoreDump\fP() family executing
concurrently.
.SH "SEE ALSO"
.BR GetCoreDump (3),
and
.BR GetCompressedCoreDump(3).