NAME

       mcd_dump_data_register_bin - register binary data to be dumped

SYNOPSIS

       #include <minicoredumper.h>

       int mcd_dump_data_register_bin(const char *ident,
                                      unsigned long dump_scope,
                                      mcd_dump_data_t *save_ptr,
                                      void *data_ptr,
                                      size_t data_size,
                                      enum mcd_dump_data_flags flags);

       Compile and link with -lminicoredumper.

DESCRIPTION

       The  mcd_dump_data_register_bin()  function  registers  binary  data  to be dumped.  ident is a string to
       identify the binary dump later. If non-NULL, it must be unique! If 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 core(5)
       file. The data will only be dumped if a scope value greater than or equal to dump_scope is  requested  by
       the  minicoredumper(1).   If save_ptr is non-NULL, a pointer to the registered dump will be stored there.
       This is needed if mcd_dump_data_unregister(3) will be used.  data_ptr contains a pointer  to  the  memory
       location  of the data to dump (or a pointer to that pointer).  flags specifies how data_ptr and data_size
       should be interpreted when dumping data.  data_size specifies the number of bytes of data to dump  (or  a
       pointer to the number).

DATA FLAGS

       The  flags  option  specifies  how data_ptr and 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:

       MCD_DATA_PTR_DIRECT
              data_ptr is a pointer to the data to dump.

       MCD_DATA_PTR_INDIRECT
              data_ptr  is  a pointer to a second pointer that points to the data to dump. The second pointer is
              evaluated at dump. See BUGS for details about the dangers of this flag.

       MCD_LENGTH_DIRECT
              data_size specifies the size (in bytes) of data to dump.

       MCD_LENGTH_INDIRECT
              data_size is a pointer to the size (in bytes) of data to dump. The pointer is evaluated  at  dump.
              See BUGS for details about the dangers of this flag.

       MCD_DATA_NODUMP
              Do  not  dump  the  specified  data and size. Only store information about where in memory and the
              core(5) file this data would be stored. This information is stored in the symbol.map dump file and
              can be used by the coreinject(1) tool to inject data to the registered location.

RETURN VALUE

       mcd_dump_data_register_bin() returns 0 on success, otherwise an error value is returned.

ERRORS

       ENOMEM Insufficient memory available to allocate internal structures.

       EINVAL data_ptr was NULL, data_size was 0, or ident was invalid.

       EEXIST A binary or text dump matching the non-NULL ident was already registered.

EXAMPLES

       Register a binary dump with direct data and direct size.

              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);

       Register a binary dump with indirect data and direct size.

              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);

       Register a binary dump with indirect data and indirect size.

              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);

BUGS

       MCD_DATA_PTR_INDIRECT  and  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.

       The  string specified in ident is also the file name of the dump file. For this reason characters such as
       '/' are not permitted.

SEE ALSO

       libminicoredumper(7), mcd_dump_data_unregister(3), coreinject(1)

       The DiaMon Workgroup: <http://www.diamon.org>