1 | #ifndef HEADER_CURL_MEMORY_H |
2 | #define |
3 | /*************************************************************************** |
4 | * _ _ ____ _ |
5 | * Project ___| | | | _ \| | |
6 | * / __| | | | |_) | | |
7 | * | (__| |_| | _ <| |___ |
8 | * \___|\___/|_| \_\_____| |
9 | * |
10 | * Copyright (C) 1998 - 2022, Daniel Stenberg, <[email protected]>, 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 https://curl.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 | * SPDX-License-Identifier: curl |
24 | * |
25 | ***************************************************************************/ |
26 | |
27 | /* |
28 | * Nasty internal details ahead... |
29 | * |
30 | * File curl_memory.h must be included by _all_ *.c source files |
31 | * that use memory related functions strdup, malloc, calloc, realloc |
32 | * or free, and given source file is used to build libcurl library. |
33 | * It should be included immediately before memdebug.h as the last files |
34 | * included to avoid undesired interaction with other memory function |
35 | * headers in dependent libraries. |
36 | * |
37 | * There is nearly no exception to above rule. All libcurl source |
38 | * files in 'lib' subdirectory as well as those living deep inside |
39 | * 'packages' subdirectories and linked together in order to build |
40 | * libcurl library shall follow it. |
41 | * |
42 | * File lib/strdup.c is an exception, given that it provides a strdup |
43 | * clone implementation while using malloc. Extra care needed inside |
44 | * this one. |
45 | * |
46 | * The need for curl_memory.h inclusion is due to libcurl's feature |
47 | * of allowing library user to provide memory replacement functions, |
48 | * memory callbacks, at runtime with curl_global_init_mem() |
49 | * |
50 | * Any *.c source file used to build libcurl library that does not |
51 | * include curl_memory.h and uses any memory function of the five |
52 | * mentioned above will compile without any indication, but it will |
53 | * trigger weird memory related issues at runtime. |
54 | * |
55 | * OTOH some source files from 'lib' subdirectory may additionally be |
56 | * used directly as source code when using some curlx_ functions by |
57 | * third party programs that don't even use libcurl at all. When using |
58 | * these source files in this way it is necessary these are compiled |
59 | * with CURLX_NO_MEMORY_CALLBACKS defined, in order to ensure that no |
60 | * attempt of calling libcurl's memory callbacks is done from code |
61 | * which can not use this machinery. |
62 | * |
63 | * Notice that libcurl's 'memory tracking' system works chaining into |
64 | * the memory callback machinery. This implies that when compiling |
65 | * 'lib' source files with CURLX_NO_MEMORY_CALLBACKS defined this file |
66 | * disengages usage of libcurl's 'memory tracking' system, defining |
67 | * MEMDEBUG_NODEFINES and overriding CURLDEBUG purpose. |
68 | * |
69 | * CURLX_NO_MEMORY_CALLBACKS takes precedence over CURLDEBUG. This is |
70 | * done in order to allow building a 'memory tracking' enabled libcurl |
71 | * and at the same time allow building programs which do not use it. |
72 | * |
73 | * Programs and libraries in 'tests' subdirectories have specific |
74 | * purposes and needs, and as such each one will use whatever fits |
75 | * best, depending additionally whether it links with libcurl or not. |
76 | * |
77 | * Caveat emptor. Proper curlx_* separation is a work in progress |
78 | * the same as CURLX_NO_MEMORY_CALLBACKS usage, some adjustments may |
79 | * still be required. IOW don't use them yet, there are sharp edges. |
80 | */ |
81 | |
82 | #ifdef HEADER_CURL_MEMDEBUG_H |
83 | #error "Header memdebug.h shall not be included before curl_memory.h" |
84 | #endif |
85 | |
86 | #ifndef CURLX_NO_MEMORY_CALLBACKS |
87 | |
88 | #ifndef CURL_DID_MEMORY_FUNC_TYPEDEFS /* only if not already done */ |
89 | /* |
90 | * The following memory function replacement typedef's are COPIED from |
91 | * curl/curl.h and MUST match the originals. We copy them to avoid having to |
92 | * include curl/curl.h here. We avoid that include since it includes stdio.h |
93 | * and other headers that may get messed up with defines done here. |
94 | */ |
95 | typedef void *(*curl_malloc_callback)(size_t size); |
96 | typedef void (*curl_free_callback)(void *ptr); |
97 | typedef void *(*curl_realloc_callback)(void *ptr, size_t size); |
98 | typedef char *(*curl_strdup_callback)(const char *str); |
99 | typedef void *(*curl_calloc_callback)(size_t nmemb, size_t size); |
100 | #define CURL_DID_MEMORY_FUNC_TYPEDEFS |
101 | #endif |
102 | |
103 | extern curl_malloc_callback Curl_cmalloc; |
104 | extern curl_free_callback Curl_cfree; |
105 | extern curl_realloc_callback Curl_crealloc; |
106 | extern curl_strdup_callback Curl_cstrdup; |
107 | extern curl_calloc_callback Curl_ccalloc; |
108 | #if defined(WIN32) && defined(UNICODE) |
109 | extern curl_wcsdup_callback Curl_cwcsdup; |
110 | #endif |
111 | |
112 | #ifndef CURLDEBUG |
113 | |
114 | /* |
115 | * libcurl's 'memory tracking' system defines strdup, malloc, calloc, |
116 | * realloc and free, along with others, in memdebug.h in a different |
117 | * way although still using memory callbacks forward declared above. |
118 | * When using the 'memory tracking' system (CURLDEBUG defined) we do |
119 | * not define here the five memory functions given that definitions |
120 | * from memdebug.h are the ones that shall be used. |
121 | */ |
122 | |
123 | #undef strdup |
124 | #define strdup(ptr) Curl_cstrdup(ptr) |
125 | #undef malloc |
126 | #define malloc(size) Curl_cmalloc(size) |
127 | #undef calloc |
128 | #define calloc(nbelem,size) Curl_ccalloc(nbelem, size) |
129 | #undef realloc |
130 | #define realloc(ptr,size) Curl_crealloc(ptr, size) |
131 | #undef free |
132 | #define free(ptr) Curl_cfree(ptr) |
133 | |
134 | #ifdef WIN32 |
135 | # ifdef UNICODE |
136 | # undef wcsdup |
137 | # define wcsdup(ptr) Curl_cwcsdup(ptr) |
138 | # undef _wcsdup |
139 | # define _wcsdup(ptr) Curl_cwcsdup(ptr) |
140 | # undef _tcsdup |
141 | # define _tcsdup(ptr) Curl_cwcsdup(ptr) |
142 | # else |
143 | # undef _tcsdup |
144 | # define _tcsdup(ptr) Curl_cstrdup(ptr) |
145 | # endif |
146 | #endif |
147 | |
148 | #endif /* CURLDEBUG */ |
149 | |
150 | #else /* CURLX_NO_MEMORY_CALLBACKS */ |
151 | |
152 | #ifndef MEMDEBUG_NODEFINES |
153 | #define MEMDEBUG_NODEFINES |
154 | #endif |
155 | |
156 | #endif /* CURLX_NO_MEMORY_CALLBACKS */ |
157 | |
158 | #endif /* HEADER_CURL_MEMORY_H */ |
159 | |