.. _man3-PMIx_Data_decompress:

PMIx_Data_decompress
====================

.. include_body

``PMIx_Data_decompress`` |mdash| Decompress a data block previously compressed by
``PMIx_Data_compress``.


SYNOPSIS
--------

.. code-block:: c

   #include <pmix.h>

   bool PMIx_Data_decompress(const uint8_t *inbytes,
                             size_t size,
                             uint8_t **outbytes,
                             size_t *nbytes);


INPUT PARAMETERS
----------------

* ``inbytes``: Pointer to the source data to be decompressed. Must not be
  ``NULL``, and must be data that was produced by
  :ref:`PMIx_Data_compress(3) <man3-PMIx_Data_compress>`.
* ``size``: Number of bytes in the source data region.


OUTPUT PARAMETERS
-----------------

* ``outbytes``: Address at which a pointer to the newly allocated decompressed
  data region is returned. On a ``true`` return this points to a buffer
  allocated by the library with ``malloc``; the caller is responsible for
  releasing it with ``free``. On a ``false`` return no buffer is produced.
* ``nbytes``: Address at which the number of bytes in the decompressed data
  region is returned.


DESCRIPTION
-----------

Decompress the provided data block. Destination memory is allocated only if the
operation is successfully concluded, and the caller is responsible for releasing
that region. The input data block remains unaltered. The method of compressing
and decompressing data is implementation dependent.

Only data compressed by the :ref:`PMIx_Data_compress(3) <man3-PMIx_Data_compress>`
API may be passed to this function. Passing data that was not produced by
``PMIx_Data_compress`` leads to undefined behavior.

The decompression is performed by the active ``pcompress`` component, which must
be compatible with the component that produced the compressed data.


RETURN VALUE
------------

Returns a ``bool``, not a ``pmix_status_t``:

* ``true`` |mdash| the input data was decompressed. ``*outbytes`` points to a
  freshly allocated buffer holding the decompressed data and ``*nbytes`` holds
  its length. The caller must ``free`` ``*outbytes`` when done.
* ``false`` |mdash| the input data was not decompressed. No output buffer is
  allocated in this case.


NOTES
-----

``PMIx_Data_decompress`` must be called only after the PMIx library has been
initialized and with a non-``NULL`` ``inbytes`` pointer; no output is produced
otherwise.

Because the compressed representation is implementation dependent, the data
supplied here must have been generated by a compatible PMIx implementation using
:ref:`PMIx_Data_compress(3) <man3-PMIx_Data_compress>`.


.. seealso::
   :ref:`PMIx_Data_compress(3) <man3-PMIx_Data_compress>`,
   :ref:`pmix_status_t(5) <man5-pmix_status_t>`
