1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Memory Allocation Subsystem</title>
<style type="text/css">
body {
margin: auto;
font-family: Verdana, sans-serif;
padding: 8px 1%;
}
a { color: #044a64 }
a:visited { color: #734559 }
.logo { position:absolute; margin:3px; }
.tagline {
float:right;
text-align:right;
font-style:italic;
width:300px;
margin:12px;
margin-top:58px;
}
.menubar {
clear: both;
border-radius: 8px;
background: #044a64;
padding: 0px;
margin: 0px;
cell-spacing: 0px;
}
.toolbar {
text-align: center;
line-height: 1.6em;
margin: 0;
padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }
.content { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }
/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a { color: darkblue ; text-decoration: none }
.fancy .todo { color: #AA3333 ; font-style : italic }
.fancy .todo:before { content: 'TODO:' }
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */
</style>
</head>
<body>
<div><!-- container div to satisfy validator -->
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
<table width=100% class="menubar"><tr>
<td width=100%>
<div class="toolbar">
<a href="../about.html">About</a>
<a href="../sitemap.html">Sitemap</a>
<a href="../docs.html">Documentation</a>
<a href="../download.html">Download</a>
<a href="../copyright.html">License</a>
<a href="../news.html">News</a>
<a href="../support.html">Support</a>
</div>
<script>
gMsg = "Search SQLite Docs..."
function entersearch() {
var q = document.getElementById("q");
if( q.value == gMsg ) { q.value = "" }
q.style.color = "black"
q.style.fontStyle = "normal"
}
function leavesearch() {
var q = document.getElementById("q");
if( q.value == "" ) {
q.value = gMsg
q.style.color = "#044a64"
q.style.fontStyle = "italic"
}
}
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
</script>
<td>
<div style="padding:0 1em 0px 0;white-space:nowrap">
<form name=f method="GET" action="http://www.sqlite.org/search">
<input id=q name=q type=text
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...">
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
</form>
</div>
</table>
<div class=startsearch></div>
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Memory Allocation Subsystem</h2><blockquote><pre>void *sqlite3_malloc(int);
void *sqlite3_malloc64(sqlite3_uint64);
void *sqlite3_realloc(void*, int);
void *sqlite3_realloc64(void*, sqlite3_uint64);
void sqlite3_free(void*);
sqlite3_uint64 sqlite3_msize(void*);
</pre></blockquote><p>
The SQLite core uses these three routines for all of its own
internal memory allocation needs. "Core" in the previous sentence
does not include operating-system specific VFS implementation. The
Windows VFS uses native malloc() and free() for some operations.</p>
<p>The sqlite3_malloc() routine returns a pointer to a block
of memory at least N bytes in length, where N is the parameter.
If sqlite3_malloc() is unable to obtain sufficient free
memory, it returns a NULL pointer. If the parameter N to
sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
a NULL pointer.</p>
<p>The sqlite3_malloc64(N) routine works just like
sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
of a signed 32-bit integer.</p>
<p>Calling sqlite3_free() with a pointer previously returned
by sqlite3_malloc() or sqlite3_realloc() releases that memory so
that it might be reused. The sqlite3_free() routine is
a no-op if is called with a NULL pointer. Passing a NULL pointer
to sqlite3_free() is harmless. After being freed, memory
should neither be read nor written. Even reading previously freed
memory might result in a segmentation fault or other severe error.
Memory corruption, a segmentation fault, or other severe error
might result if sqlite3_free() is called with a non-NULL pointer that
was not obtained from sqlite3_malloc() or sqlite3_realloc().</p>
<p>The sqlite3_realloc(X,N) interface attempts to resize a
prior memory allocation X to be at least N bytes.
If the X parameter to sqlite3_realloc(X,N)
is a NULL pointer then its behavior is identical to calling
sqlite3_malloc(N).
If the N parameter to sqlite3_realloc(X,N) is zero or
negative then the behavior is exactly the same as calling
sqlite3_free(X).
sqlite3_realloc(X,N) returns a pointer to a memory allocation
of at least N bytes in size or NULL if insufficient memory is available.
If M is the size of the prior allocation, then min(N,M) bytes
of the prior allocation are copied into the beginning of buffer returned
by sqlite3_realloc(X,N) and the prior allocation is freed.
If sqlite3_realloc(X,N) returns NULL and N is positive, then the
prior allocation is not freed.</p>
<p>The sqlite3_realloc64(X,N) interfaces works the same as
sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
of a 32-bit signed integer.</p>
<p>If X is a memory allocation previously obtained from sqlite3_malloc(),
sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
sqlite3_msize(X) returns the size of that memory allocation in bytes.
The value returned by sqlite3_msize(X) might be larger than the number
of bytes requested when X was allocated. If X is a NULL pointer then
sqlite3_msize(X) returns zero. If X points to something that is not
the beginning of memory allocation, or if it points to a formerly
valid memory allocation that has now been freed, then the behavior
of sqlite3_msize(X) is undefined and possibly harmful.</p>
<p>The memory returned by sqlite3_malloc(), sqlite3_realloc(),
sqlite3_malloc64(), and sqlite3_realloc64()
is always aligned to at least an 8 byte boundary, or to a
4 byte boundary if the <a href="../compile.html#4_byte_aligned_malloc">SQLITE_4_BYTE_ALIGNED_MALLOC</a> compile-time
option is used.</p>
<p>In SQLite version 3.5.0 and 3.5.1, it was possible to define
the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
implementation of these routines to be omitted. That capability
is no longer provided. Only built-in memory allocators can be used.</p>
<p>Prior to SQLite version 3.7.10, the Windows OS interface layer called
the system malloc() and free() directly when converting
filenames between the UTF-8 encoding used by SQLite
and whatever filename encoding is used by the particular Windows
installation. Memory allocation errors were detected, but
they were reported back as <a href="../rescode.html#cantopen">SQLITE_CANTOPEN</a> or
<a href="../rescode.html#ioerr">SQLITE_IOERR</a> rather than <a href="../rescode.html#nomem">SQLITE_NOMEM</a>.</p>
<p>The pointer arguments to <a href="../c3ref/free.html">sqlite3_free()</a> and <a href="../c3ref/free.html">sqlite3_realloc()</a>
must be either NULL or else pointers obtained from a prior
invocation of <a href="../c3ref/free.html">sqlite3_malloc()</a> or <a href="../c3ref/free.html">sqlite3_realloc()</a> that have
not yet been released.</p>
<p>The application must not read or write any part of
a block of memory after it has been released using
<a href="../c3ref/free.html">sqlite3_free()</a> or <a href="../c3ref/free.html">sqlite3_realloc()</a>.
</p><p>See also lists of
<a href="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
