1WRITECOREDUMP(3)           Library Functions Manual           WRITECOREDUMP(3)
2
3
4

NAME

6       WriteCoreDump,   WriteCoreDumpWith,   WriteCoreDumpLimited,  WriteCore‐
7       DumpLimitedByPriority,  WriteCompressedCoreDump - writes a snapshot  of
8       the current process
9

SYNOPSIS

11       #include “google/coredumper.h”
12
13       int WriteCoreDump(const char *file_name);
14
15       int WriteCoreDumpWith(const char *file_name, const struct CoreDump‐
16       Parameters *params);
17
18       int WriteCoreDumpLimited(const char *file_name, size_t max_length);
19
20       int WriteCoreDumpLimitedByPriority(const char *file_name, size_t
21       max_length);
22
23       int WriteCompressedCoreDump(const char *file_name, size_t max_length,
24                                   const struct CoredumperCompressor
25                                   compressors[], struct CoredumperCompressor
26                                   **selected_compressor);
27

DESCRIPTION

29       The WriteCoreDump() function writes a  core  file  to  file_name.   The
30       calling process continues running after the file has been written. This
31       is a convenience wrapper  for  WriteCoreDumpWith()  using  the  default
32       parameters.
33
34       The  WriteCoreDumpWith() function writes a core file to file_name using
35       the parameters specified in the  CoreDumpParameters()  structure.  This
36       allows for various combinations of configurations.
37
38       The WriteCoreDumpLimited() function restricts the maximum length of the
39       written file. This is similar to what setting calling setrlimit(2) does
40       for  system-generated  core  files.  This  is a convenience wrapper for
41       WriteCoreDumpWith().
42
43       The WriteCoreDumpLimitedByPriority()  function  restricts  the  maximum
44       length  of the written file, however it does so by prioritizing smaller
45       memory segments. This means that the core file is not truncated at  the
46       end  of  the  file, as in WriteCoreDumpLimited(), but individual memory
47       segments in the core file are truncated with the largest segments trun‐
48       cated first. This is a convenience wrapper for WriteCoreDumpWith().
49
50       The  WriteCompressedCoreDump()  function  attempts to compress the core
51       file on the fly, if a suitable compressor could be located.
52
53       If selected_compressor is non-NULL, it will be set to the actual  Core‐
54       dumperCompressor object used.
55
56       The  filename  automatically has a suitable suffix appended to it. Nor‐
57       mally this would be “.bz2” for bzip2(1) compression, “.gz” for  gzip(1)
58       compression,  or “.Z” for compress(1) compression. This behavior can be
59       changed by defining custom CoredumperCompressor descriptions. This is a
60       convenience  wrapper  for  WriteCoreDumpWith(). See the manual page for
61       GetCoreDump(3) for more details.
62

RETURN VALUE

64       WriteCoreDump(),      WriteCoreDumpWith(),      WriteCoreDumpLimited(),
65       WriteCoreDumpLimitedByPriority(),  and WriteCompressedCoreDump() return
66       zero on success and -1 on failure. In case of failure,  errno  will  be
67       set appropriately.
68

ERRORS

70       The  most  common  reason for failure is for another process to already
71       use the debugging API that is needed to generate the core  files.  This
72       could, for instance, be gdb(1), or strace(1).
73

NOTES

75       The  coredumper functions momentarily suspend all threads, while creat‐
76       ing a COW (copy-on-write) copy of the process's address space.
77
78       The functions are neither reentrant  nor  async  signal  safe.  Callers
79       should wrap a mutex around their invocation, if necessary.
80
81       The  current  implementation  tries very hard to behave reasonably when
82       called from a signal handler, but no guarantees are made that this will
83       always  work.  Most  importantly,  it is the caller's responsibility to
84       make sure that there are never more than one instance of functions from
85       the GetCoreDump() or WriteCoreDump() family executing concurrently.
86

SEE ALSO

88       GetCoreDump(3), GetCoreDumpWith(3), GetCompressedCoreDump(3), and Core‐
89       DumpParameters(3).
90
91
92
93                                 Feb 15, 2007                 WRITECOREDUMP(3)
Impressum