xref: /curl/docs/libcurl/curl_global_init_mem.md (revision 3040971d) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_global_init_mem
5Section: 3
6Source: libcurl
7See-also:
8  - curl_global_cleanup (3)
9  - curl_global_init (3)
10Protocol:
11  - All
12Added-in: 7.12.0
13---
14
15# NAME
16
17curl_global_init_mem - global libcurl initialization with memory callbacks
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLcode curl_global_init_mem(long flags,
25                              curl_malloc_callback m,
26                              curl_free_callback f,
27                              curl_realloc_callback r,
28                              curl_strdup_callback s,
29                              curl_calloc_callback c);
30~~~
31
32# DESCRIPTION
33
34This function works exactly as curl_global_init(3) with one addition: it
35allows the application to set callbacks to replace the otherwise used internal
36memory functions.
37
38If you are using libcurl from multiple threads or libcurl was built with the
39threaded resolver option then the callback functions must be thread safe. The
40threaded resolver is a common build option to enable (and in some cases the
41default) so we strongly urge you to make your callback functions thread safe.
42
43All callback arguments must be set to valid function pointers. The
44prototypes for the given callbacks must match these:
45
46## `void *malloc_callback(size_t size);`
47
48To replace malloc()
49
50## `void free_callback(void *ptr);`
51
52To replace free()
53
54## `void *realloc_callback(void *ptr, size_t size);`
55
56To replace realloc()
57
58## `char *strdup_callback(const char *str);`
59
60To replace strdup()
61
62## `void *calloc_callback(size_t nmemb, size_t size);`
63
64To replace calloc()
65
66This function is otherwise the same as curl_global_init(3), please refer
67to that man page for documentation.
68
69# CAUTION
70
71Manipulating these gives considerable powers to the application to severely
72screw things up for libcurl. Take care.
73
74# %PROTOCOLS%
75
76# EXAMPLE
77
78~~~c
79extern void *malloc_cb(size_t);
80extern void free_cb(void *);
81extern void *realloc_cb(void *, size_t);
82extern char *strdup_cb(const char *);
83extern void *calloc_cb(size_t, size_t);
84
85int main(void)
86{
87  curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb,
88                       free_cb, realloc_cb,
89                       strdup_cb, calloc_cb);
90}
91~~~
92
93# %AVAILABILITY%
94
95# RETURN VALUE
96
97CURLE_OK (0) means everything was OK, non-zero means an error occurred as
98*\<curl/curl.h\>* defines - see libcurl-errors(3).
99