windows/liblzma-crt-mixing.txt

   1
   2 liblzma.dll and mixing C runtimes (CRTs)
   3 ----------------------------------------
   4
   5     If possible, liblzma.dll should be linked against the same CRT
   6     (MSVCRT or UCRT) as the application calling the liblzma functions.
   7     When this isn't possible, liblzma.dll will still work but there
   8     are a few API functions that need extra care.
   9
  10     Each CRT has its own memory allocator, stdio FILE implementation,
  11     mapping of file descriptors from _open() to Windows' HANDLEs, and
  12     so on. Mixing CRTs is a problem if, for example, one library calls
  13     fopen() and then passes the resulting FILE* to a second library and
  14     these two libraries use different CRTs. liblzma doesn't expose FILE
  15     pointers or file descriptors in the API but the problem can occur
  16     with memory allocation with a few specific functions.
  17
  18     The most commonly-used API functions in liblzma are such that both
  19     memory allocation and deallocation is done internally by liblzma,
  20     thus most applications won't have any problems with mixing CRTs
  21     with liblzma.dll. The following API functions are the exception:
  22
  23         lzma/block.h:
  24             lzma_block_header_decode
  25
  26         lzma/filter.h:
  27             lzma_filters_copy
  28             lzma_filters_free
  29             lzma_properties_decode
  30             lzma_filter_flags_decode
  31             lzma_str_to_filters
  32             lzma_str_from_filters
  33             lzma_str_list_filters
  34
  35     Excluding lzma_filters_free(), the above functions allocate memory
  36     and leave it to the caller to free it. lzma_filters_free() frees
  37     memory given to it, and that memory may have been allocated outside
  38     of liblzma.
  39
  40     For example, if application calls lzma_str_list_filters(&ptr, ...)
  41     and then uses free(ptr), something bad (memory corruption, crash)
  42     will happen if the application and liblzma.dll aren't using the
  43     same CRT. This can be worked around with a few lines of extra code.
  44
  45     All these functions (and many others too) take a pointer to
  46     lzma_allocator structure as an argument. Typically it is set to
  47     NULL to let liblzma use malloc() and free() (and also calloc()
  48     as it is faster than malloc() + memset()). A custom lzma_allocator
  49     can be used to wrap malloc() and free() from application's CRT:
  50
  51         static void * LZMA_API_CALL
  52         my_alloc(void *opaque, size_t nmemb, size_t size)
  53         {
  54             // liblzma guarantees that this won't overflow.
  55             return malloc(nmemb * size);
  56         }
  57
  58         static void LZMA_API_CALL
  59         my_free(void *opaque, void *ptr)
  60         {
  61             free(ptr);
  62         }
  63
  64         static const lzma_allocator allocator
  65                 = { &my_alloc, &my_free, NULL };
  66
  67     By passing &allocator to the problematic functions, CRT mixing
  68     should not cause any problems. There is no need to use &allocator
  69     with functions other than those listed above.
  70