curl_memory.h 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. #ifndef HEADER_CURL_MEMORY_H
  2. #define HEADER_CURL_MEMORY_H
  3. /***************************************************************************
  4. * _ _ ____ _
  5. * Project ___| | | | _ \| |
  6. * / __| | | | |_) | |
  7. * | (__| |_| | _ <| |___
  8. * \___|\___/|_| \_\_____|
  9. *
  10. * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
  11. *
  12. * This software is licensed as described in the file COPYING, which
  13. * you should have received as part of this distribution. The terms
  14. * are also available at http://curl.haxx.se/docs/copyright.html.
  15. *
  16. * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  17. * copies of the Software, and permit persons to whom the Software is
  18. * furnished to do so, under the terms of the COPYING file.
  19. *
  20. * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  21. * KIND, either express or implied.
  22. *
  23. ***************************************************************************/
  24. /*
  25. * Nasty internal details ahead...
  26. *
  27. * File curl_memory.h must be included by _all_ *.c source files
  28. * that use memory related functions strdup, malloc, calloc, realloc
  29. * or free, and given source file is used to build libcurl library.
  30. *
  31. * There is nearly no exception to above rule. All libcurl source
  32. * files in 'lib' subdirectory as well as those living deep inside
  33. * 'packages' subdirectories and linked together in order to build
  34. * libcurl library shall follow it.
  35. *
  36. * File lib/strdup.c is an exception, given that it provides a strdup
  37. * clone implementation while using malloc. Extra care needed inside
  38. * this one. TODO: revisit this paragraph and related code.
  39. *
  40. * The need for curl_memory.h inclusion is due to libcurl's feature
  41. * of allowing library user to provide memory replacement functions,
  42. * memory callbacks, at runtime with curl_global_init_mem()
  43. *
  44. * Any *.c source file used to build libcurl library that does not
  45. * include curl_memory.h and uses any memory function of the five
  46. * mentioned above will compile without any indication, but it will
  47. * trigger weird memory related issues at runtime.
  48. *
  49. * OTOH some source files from 'lib' subdirectory may additionally be
  50. * used directly as source code when using some curlx_ functions by
  51. * third party programs that don't even use libcurl at all. When using
  52. * these source files in this way it is necessary these are compiled
  53. * with CURLX_NO_MEMORY_CALLBACKS defined, in order to ensure that no
  54. * attempt of calling libcurl's memory callbacks is done from code
  55. * which can not use this machinery.
  56. *
  57. * Notice that libcurl's 'memory tracking' system works chaining into
  58. * the memory callback machinery. This implies that when compiling
  59. * 'lib' source files with CURLX_NO_MEMORY_CALLBACKS defined this file
  60. * disengages usage of libcurl's 'memory tracking' system, defining
  61. * MEMDEBUG_NODEFINES and overriding CURLDEBUG purpose.
  62. *
  63. * CURLX_NO_MEMORY_CALLBACKS takes precedence over CURLDEBUG. This is
  64. * done in order to allow building a 'memory tracking' enabled libcurl
  65. * and at the same time allow building programs which do not use it.
  66. *
  67. * Programs and libraries in 'tests' subdirectories have specific
  68. * purposes and needs, and as such each one will use whatever fits
  69. * best, depending additionally wether it links with libcurl or not.
  70. *
  71. * Caveat emptor. Proper curlx_* separation is a work in progress
  72. * the same as CURLX_NO_MEMORY_CALLBACKS usage, some adjustments may
  73. * still be required. IOW don't use them yet, there are sharp edges.
  74. */
  75. #ifdef HEADER_CURL_MEMDEBUG_H
  76. #error "Header memdebug.h shall not be included before curl_memory.h"
  77. #endif
  78. #ifndef CURLX_NO_MEMORY_CALLBACKS
  79. #include <curl/curl.h> /* for the callback typedefs */
  80. extern curl_malloc_callback Curl_cmalloc;
  81. extern curl_free_callback Curl_cfree;
  82. extern curl_realloc_callback Curl_crealloc;
  83. extern curl_strdup_callback Curl_cstrdup;
  84. extern curl_calloc_callback Curl_ccalloc;
  85. #if defined(WIN32) && defined(UNICODE)
  86. extern curl_wcsdup_callback Curl_cwcsdup;
  87. #endif
  88. #ifndef CURLDEBUG
  89. /*
  90. * libcurl's 'memory tracking' system defines strdup, malloc, calloc,
  91. * realloc and free, along with others, in memdebug.h in a different
  92. * way although still using memory callbacks forward declared above.
  93. * When using the 'memory tracking' system (CURLDEBUG defined) we do
  94. * not define here the five memory functions given that definitions
  95. * from memdebug.h are the ones that shall be used.
  96. */
  97. #undef strdup
  98. #define strdup(ptr) Curl_cstrdup(ptr)
  99. #undef malloc
  100. #define malloc(size) Curl_cmalloc(size)
  101. #undef calloc
  102. #define calloc(nbelem,size) Curl_ccalloc(nbelem, size)
  103. #undef realloc
  104. #define realloc(ptr,size) Curl_crealloc(ptr, size)
  105. #undef free
  106. #define free(ptr) Curl_cfree(ptr)
  107. #ifdef WIN32
  108. # ifdef UNICODE
  109. # undef wcsdup
  110. # define wcsdup(ptr) Curl_cwcsdup(ptr)
  111. # undef _wcsdup
  112. # define _wcsdup(ptr) Curl_cwcsdup(ptr)
  113. # undef _tcsdup
  114. # define _tcsdup(ptr) Curl_cwcsdup(ptr)
  115. # else
  116. # undef _tcsdup
  117. # define _tcsdup(ptr) Curl_cstrdup(ptr)
  118. # endif
  119. #endif
  120. #endif /* CURLDEBUG */
  121. #else /* CURLX_NO_MEMORY_CALLBACKS */
  122. #ifndef MEMDEBUG_NODEFINES
  123. #define MEMDEBUG_NODEFINES
  124. #endif
  125. #endif /* CURLX_NO_MEMORY_CALLBACKS */
  126. #endif /* HEADER_CURL_MEMORY_H */