1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Memory Allocation Subsystem</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Memory Allocation Subsystem</h2><blockquote><pre>void *sqlite3_malloc(int);
121
void *sqlite3_realloc(void*, int);
122
void sqlite3_free(void*);
123
</pre></blockquote><p>
124
The SQLite core uses these three routines for all of its own
125
internal memory allocation needs. "Core" in the previous sentence
126
does not include operating-system specific VFS implementation. The
127
Windows VFS uses native malloc() and free() for some operations.</p>
129
<p>The sqlite3_malloc() routine returns a pointer to a block
130
of memory at least N bytes in length, where N is the parameter.
131
If sqlite3_malloc() is unable to obtain sufficient free
132
memory, it returns a NULL pointer. If the parameter N to
133
sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
136
<p>Calling sqlite3_free() with a pointer previously returned
137
by sqlite3_malloc() or sqlite3_realloc() releases that memory so
138
that it might be reused. The sqlite3_free() routine is
139
a no-op if is called with a NULL pointer. Passing a NULL pointer
140
to sqlite3_free() is harmless. After being freed, memory
141
should neither be read nor written. Even reading previously freed
142
memory might result in a segmentation fault or other severe error.
143
Memory corruption, a segmentation fault, or other severe error
144
might result if sqlite3_free() is called with a non-NULL pointer that
145
was not obtained from sqlite3_malloc() or sqlite3_realloc().</p>
147
<p>The sqlite3_realloc() interface attempts to resize a
148
prior memory allocation to be at least N bytes, where N is the
149
second parameter. The memory allocation to be resized is the first
150
parameter. If the first parameter to sqlite3_realloc()
151
is a NULL pointer then its behavior is identical to calling
152
sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
153
If the second parameter to sqlite3_realloc() is zero or
154
negative then the behavior is exactly the same as calling
155
sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
156
sqlite3_realloc() returns a pointer to a memory allocation
157
of at least N bytes in size or NULL if sufficient memory is unavailable.
158
If M is the size of the prior allocation, then min(N,M) bytes
159
of the prior allocation are copied into the beginning of buffer returned
160
by sqlite3_realloc() and the prior allocation is freed.
161
If sqlite3_realloc() returns NULL, then the prior allocation
164
<p>The memory returned by sqlite3_malloc() and sqlite3_realloc()
165
is always aligned to at least an 8 byte boundary, or to a
166
4 byte boundary if the <a href="../compile.html#4_byte_aligned_malloc">SQLITE_4_BYTE_ALIGNED_MALLOC</a> compile-time
169
<p>In SQLite version 3.5.0 and 3.5.1, it was possible to define
170
the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
171
implementation of these routines to be omitted. That capability
172
is no longer provided. Only built-in memory allocators can be used.</p>
174
<p>Prior to SQLite version 3.7.10, the Windows OS interface layer called
175
the system malloc() and free() directly when converting
176
filenames between the UTF-8 encoding used by SQLite
177
and whatever filename encoding is used by the particular Windows
178
installation. Memory allocation errors were detected, but
179
they were reported back as <a href="../c3ref/c_abort.html">SQLITE_CANTOPEN</a> or
180
<a href="../c3ref/c_abort.html">SQLITE_IOERR</a> rather than <a href="../c3ref/c_abort.html">SQLITE_NOMEM</a>.</p>
182
<p>The pointer arguments to <a href="../c3ref/free.html">sqlite3_free()</a> and <a href="../c3ref/free.html">sqlite3_realloc()</a>
183
must be either NULL or else pointers obtained from a prior
184
invocation of <a href="../c3ref/free.html">sqlite3_malloc()</a> or <a href="../c3ref/free.html">sqlite3_realloc()</a> that have
185
not yet been released.</p>
187
<p>The application must not read or write any part of
188
a block of memory after it has been released using
189
<a href="../c3ref/free.html">sqlite3_free()</a> or <a href="../c3ref/free.html">sqlite3_realloc()</a>.
190
</p><p>See also lists of
191
<a href="objlist.html">Objects</a>,
192
<a href="constlist.html">Constants</a>, and
193
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/free.html
