.. _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 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) `. * ``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) ` 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) `. .. seealso:: :ref:`PMIx_Data_compress(3) `, :ref:`pmix_status_t(5) `