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
226
227
228
229
230
231
232
233
|
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#ifndef NSSBASE_H
#define NSSBASE_H
/*
* nssbase.h
*
* This header file contains the prototypes of the basic public
* NSS routines.
*/
#ifndef NSSBASET_H
#include "nssbaset.h"
#endif /* NSSBASET_H */
PR_BEGIN_EXTERN_C
/*
* NSSArena
*
* The public methods relating to this type are:
*
* NSSArena_Create -- constructor
* NSSArena_Destroy
* NSS_ZAlloc
* NSS_ZRealloc
* NSS_ZFreeIf
*/
/*
* NSSArena_Create
*
* This routine creates a new memory arena. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The top-level error may be one of the following values:
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSArena upon success
*/
NSS_EXTERN NSSArena *NSSArena_Create(void);
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSArena_Destroy
*
* This routine will destroy the specified arena, freeing all memory
* allocated from it. This routine returns a PRStatus value; if
* successful, it will return PR_SUCCESS. If unsuccessful, it will
* create an error stack and return PR_FAILURE.
*
* The top-level error may be one of the following values:
* NSS_ERROR_INVALID_ARENA
*
* Return value:
* PR_SUCCESS upon success
* PR_FAILURE upon failure
*/
NSS_EXTERN PRStatus NSSArena_Destroy(NSSArena *arena);
extern const NSSError NSS_ERROR_INVALID_ARENA;
/*
* The error stack
*
* The public methods relating to the error stack are:
*
* NSS_GetError
* NSS_GetErrorStack
*/
/*
* NSS_GetError
*
* This routine returns the highest-level (most general) error set
* by the most recent NSS library routine called by the same thread
* calling this routine.
*
* This routine cannot fail. It may return NSS_ERROR_NO_ERROR, which
* indicates that the previous NSS library call did not set an error.
*
* Return value:
* 0 if no error has been set
* A nonzero error number
*/
NSS_EXTERN NSSError NSS_GetError(void);
extern const NSSError NSS_ERROR_NO_ERROR;
/*
* NSS_GetErrorStack
*
* This routine returns a pointer to an array of NSSError values,
* containingthe entire sequence or "stack" of errors set by the most
* recent NSS library routine called by the same thread calling this
* routine. NOTE: the caller DOES NOT OWN the memory pointed to by
* the return value. The pointer will remain valid until the calling
* thread calls another NSS routine. The lowest-level (most specific)
* error is first in the array, and the highest-level is last. The
* array is zero-terminated. This routine may return NULL upon error;
* this indicates a low-memory situation.
*
* Return value:
* NULL upon error, which is an implied NSS_ERROR_NO_MEMORY
* A NON-caller-owned pointer to an array of NSSError values
*/
NSS_EXTERN NSSError *NSS_GetErrorStack(void);
/*
* NSS_ZNEW
*
* This preprocessor macro will allocate memory for a new object
* of the specified type with nss_ZAlloc, and will cast the
* return value appropriately. If the optional arena argument is
* non-null, the memory will be obtained from that arena; otherwise,
* the memory will be obtained from the heap. This routine may
* return NULL upon error, in which case it will have set an error
* upon the error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ARENA
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to the new segment of zeroed memory
*/
#define NSS_ZNEW(arenaOpt, type) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type)))
/*
* NSS_ZNEWARRAY
*
* This preprocessor macro will allocate memory for an array of
* new objects, and will cast the return value appropriately.
* If the optional arena argument is non-null, the memory will
* be obtained from that arena; otherwise, the memory will be
* obtained from the heap. This routine may return NULL upon
* error, in which case it will have set an error upon the error
* stack. The array size may be specified as zero.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ARENA
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to the new segment of zeroed memory
*/
#define NSS_ZNEWARRAY(arenaOpt, type, quantity) \
((type *)NSS_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
/*
* NSS_ZAlloc
*
* This routine allocates and zeroes a section of memory of the
* size, and returns to the caller a pointer to that memory. If
* the optional arena argument is non-null, the memory will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in
* which case it will have set an error upon the error stack. The
* value specified for size may be zero; in which case a valid
* zero-length block of memory will be allocated. This block may
* be expanded by calling NSS_ZRealloc.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ARENA
* NSS_ERROR_NO_MEMORY
* NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
*
* Return value:
* NULL upon error
* A pointer to the new segment of zeroed memory
*/
NSS_EXTERN void *NSS_ZAlloc(NSSArena *arenaOpt, PRUint32 size);
/*
* NSS_ZRealloc
*
* This routine reallocates a block of memory obtained by calling
* nss_ZAlloc or nss_ZRealloc. The portion of memory
* between the new and old sizes -- which is either being newly
* obtained or released -- is in either case zeroed. This routine
* may return NULL upon failure, in which case it will have placed
* an error on the error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_POINTER
* NSS_ERROR_NO_MEMORY
* NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
*
* Return value:
* NULL upon error
* A pointer to the replacement segment of memory
*/
NSS_EXTERN void *NSS_ZRealloc(void *pointer, PRUint32 newSize);
/*
* NSS_ZFreeIf
*
* If the specified pointer is non-null, then the region of memory
* to which it points -- which must have been allocated with
* nss_ZAlloc -- will be zeroed and released. This routine
* returns a PRStatus value; if successful, it will return PR_SUCCESS.
* If unsuccessful, it will set an error on the error stack and return
* PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_POINTER
*
* Return value:
* PR_SUCCESS
* PR_FAILURE
*/
NSS_EXTERN PRStatus NSS_ZFreeIf(void *pointer);
PR_END_EXTERN_C
#endif /* NSSBASE_H */
|
