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>