'\" t
.\"
.\" Copyright (c) 2015-2018 Linutronix GmbH. All rights reserved.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.TH MCD_DUMP_DATA_REGISTER_BIN 3 "2016-09-12" "minicoredumper" "minicoredumper"
.
.SH NAME
mcd_dump_data_register_bin \- register binary data to be dumped
.
.SH SYNOPSIS
.nf
.B #include <minicoredumper.h>

.BI "int mcd_dump_data_register_bin(const char *" ident ,
.BI "                               unsigned long " dump_scope ,
.BI "                               mcd_dump_data_t *" save_ptr ,
.BI "                               void *" data_ptr ,
.BI "                               size_t " data_size ,
.BI "                               enum mcd_dump_data_flags " flags );
.fi
.PP
Compile and link with
.IR -lminicoredumper .
.
.SH DESCRIPTION
The
.BR mcd_dump_data_register_bin ()
function registers binary data to be dumped.
.I ident
is a string to identify the binary dump later. If non-NULL, it must be
unique! If
.I ident
is NULL, the data is only dumped if this is the crashing application,
in which case the data will be explicitly stored in the
.BR core (5)
file. The data will only be dumped if a scope value greater than or equal to
.I dump_scope
is requested by the
.BR minicoredumper (1).
If
.I save_ptr
is non-NULL, a pointer to the registered dump will be stored there. This
is needed if
.BR mcd_dump_data_unregister (3)
will be used.
.I data_ptr
contains a pointer to the memory location of the data to dump (or a pointer
to that pointer).
.I flags
specifies how
.I data_ptr
and
.I data_size
should be interpreted when dumping data.
.I data_size
specifies the number of bytes of data to dump (or a pointer to the number).
.
.SH "DATA FLAGS"
The
.I flags
option specifies how
.I data_ptr
and
.I data_size
should be interpreted when dumping data. It can also affect dump behavior.
The flags are bitwise combined to describe the desired behavior. The flags
available are:
.TP
.B MCD_DATA_PTR_DIRECT
.I data_ptr
is a pointer to the data to dump.
.TP
.B MCD_DATA_PTR_INDIRECT
.I data_ptr
is a pointer to a second pointer that points to the data to dump. The
second pointer is evaluated at dump. See
.B BUGS
for details about the dangers of this flag.
.TP
.B MCD_LENGTH_DIRECT
.I data_size
specifies the size (in bytes) of data to dump.
.TP
.B MCD_LENGTH_INDIRECT
.I data_size
is a pointer to the size (in bytes) of data to dump. The pointer is
evaluated at dump. See
.B BUGS
for details about the dangers of this flag.
.TP
.B MCD_DATA_NODUMP
Do not dump the specified data and size. Only store information about
where in memory and the
.BR core (5)
file this data would be stored. This information is stored in the
.I symbol.map
dump file and can be used by the
.BR coreinject (1) 
tool to inject data to the registered location.
.
.SH "RETURN VALUE"
.BR mcd_dump_data_register_bin ()
returns 0 on success, otherwise an error value is returned.
.
.SH ERRORS
.TP
.B ENOMEM
Insufficient memory available to allocate internal structures.
.TP
.B EINVAL
.I data_ptr
was NULL,
.I data_size
was 0, or
.I ident
was invalid.
.TP
.B EEXIST
A binary or text dump matching the non-NULL
.I ident
was already registered.
.
.SH EXAMPLES
Register a binary dump with direct data and direct size.
.PP
.RS
.nf
mcd_dump_data_t dd1;
unsigned long val1;

mcd_dump_data_register_bin("bdump1.bin", 6, &dd1, &val1, sizeof(val1),
                           MCD_DATA_PTR_DIRECT | MCD_LENGTH_DIRECT);
.fi
.RE
.PP
Register a binary dump with indirect data and direct size.
.PP
.RS
.nf
mcd_dump_data_t dd2;
unsigned long *val2;

val2 = malloc(sizeof(unsigned long));

mcd_dump_data_register_bin("bdump2.bin", 6, &dd2, &val2, sizeof(*val2),
                           MCD_DATA_PTR_INDIRECT | MCD_LENGTH_DIRECT);
.fi
.RE
.PP
Register a binary dump with indirect data and indirect size.
.PP
.RS
.nf
mcd_dump_data_t dd3;
unsigned long *val3;
size_t s3;

s3 = sizeof(unsigned long);
val3 = malloc(s3);

mcd_dump_data_register_bin("bdump3.bin", 6, &dd3, &val3, (size_t)&s3,
                           MCD_DATA_PTR_INDIRECT | MCD_LENGTH_INDIRECT);
.fi
.RE
.
.SH BUGS
.I MCD_DATA_PTR_INDIRECT
and
.I MCD_LENGTH_INDIRECT
allow an application to change the size and location of data to dump
during run-time. However, such changes should be performed carefully
because an application can not know when a dump will occur.
.PP
The string specified in
.I ident
is also the file name of the dump file. For this reason characters
such as '/' are not permitted.
.
.SH "SEE ALSO"
.BR libminicoredumper (7),
.BR mcd_dump_data_unregister (3),
.BR coreinject (1)
.PP
The DiaMon Workgroup: <http://www.diamon.org>