| OLD | NEW |
| 1 /* This Source Code Form is subject to the terms of the Mozilla Public | 1 /* This Source Code Form is subject to the terms of the Mozilla Public |
| 2 * License, v. 2.0. If a copy of the MPL was not distributed with this | 2 * License, v. 2.0. If a copy of the MPL was not distributed with this |
| 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ | 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| 4 | 4 |
| 5 #ifndef NSSBASE_H | 5 #ifndef NSSBASE_H |
| 6 #define NSSBASE_H | 6 #define NSSBASE_H |
| 7 | 7 |
| 8 /* | 8 /* |
| 9 * nssbase.h | 9 * nssbase.h |
| 10 * | 10 * |
| (...skipping 26 matching lines...) Expand all Loading... |
| 37 * NULL upon error, in which case it will have created an error stack. | 37 * NULL upon error, in which case it will have created an error stack. |
| 38 * | 38 * |
| 39 * The top-level error may be one of the following values: | 39 * The top-level error may be one of the following values: |
| 40 * NSS_ERROR_NO_MEMORY | 40 * NSS_ERROR_NO_MEMORY |
| 41 * | 41 * |
| 42 * Return value: | 42 * Return value: |
| 43 * NULL upon error | 43 * NULL upon error |
| 44 * A pointer to an NSSArena upon success | 44 * A pointer to an NSSArena upon success |
| 45 */ | 45 */ |
| 46 | 46 |
| 47 NSS_EXTERN NSSArena * | 47 NSS_EXTERN NSSArena *NSSArena_Create(void); |
| 48 NSSArena_Create | |
| 49 ( | |
| 50 void | |
| 51 ); | |
| 52 | 48 |
| 53 extern const NSSError NSS_ERROR_NO_MEMORY; | 49 extern const NSSError NSS_ERROR_NO_MEMORY; |
| 54 | 50 |
| 55 /* | 51 /* |
| 56 * NSSArena_Destroy | 52 * NSSArena_Destroy |
| 57 * | 53 * |
| 58 * This routine will destroy the specified arena, freeing all memory | 54 * This routine will destroy the specified arena, freeing all memory |
| 59 * allocated from it. This routine returns a PRStatus value; if | 55 * allocated from it. This routine returns a PRStatus value; if |
| 60 * successful, it will return PR_SUCCESS. If unsuccessful, it will | 56 * successful, it will return PR_SUCCESS. If unsuccessful, it will |
| 61 * create an error stack and return PR_FAILURE. | 57 * create an error stack and return PR_FAILURE. |
| 62 * | 58 * |
| 63 * The top-level error may be one of the following values: | 59 * The top-level error may be one of the following values: |
| 64 * NSS_ERROR_INVALID_ARENA | 60 * NSS_ERROR_INVALID_ARENA |
| 65 * | 61 * |
| 66 * Return value: | 62 * Return value: |
| 67 * PR_SUCCESS upon success | 63 * PR_SUCCESS upon success |
| 68 * PR_FAILURE upon failure | 64 * PR_FAILURE upon failure |
| 69 */ | 65 */ |
| 70 | 66 |
| 71 NSS_EXTERN PRStatus | 67 NSS_EXTERN PRStatus NSSArena_Destroy(NSSArena *arena); |
| 72 NSSArena_Destroy | |
| 73 ( | |
| 74 NSSArena *arena | |
| 75 ); | |
| 76 | 68 |
| 77 extern const NSSError NSS_ERROR_INVALID_ARENA; | 69 extern const NSSError NSS_ERROR_INVALID_ARENA; |
| 78 | 70 |
| 79 /* | 71 /* |
| 80 * The error stack | 72 * The error stack |
| 81 * | 73 * |
| 82 * The public methods relating to the error stack are: | 74 * The public methods relating to the error stack are: |
| 83 * | 75 * |
| 84 * NSS_GetError | 76 * NSS_GetError |
| 85 * NSS_GetErrorStack | 77 * NSS_GetErrorStack |
| 86 */ | 78 */ |
| 87 | 79 |
| 88 /* | 80 /* |
| 89 * NSS_GetError | 81 * NSS_GetError |
| 90 * | 82 * |
| 91 * This routine returns the highest-level (most general) error set | 83 * This routine returns the highest-level (most general) error set |
| 92 * by the most recent NSS library routine called by the same thread | 84 * by the most recent NSS library routine called by the same thread |
| 93 * calling this routine. | 85 * calling this routine. |
| 94 * | 86 * |
| 95 * This routine cannot fail. It may return NSS_ERROR_NO_ERROR, which | 87 * This routine cannot fail. It may return NSS_ERROR_NO_ERROR, which |
| 96 * indicates that the previous NSS library call did not set an error. | 88 * indicates that the previous NSS library call did not set an error. |
| 97 * | 89 * |
| 98 * Return value: | 90 * Return value: |
| 99 * 0 if no error has been set | 91 * 0 if no error has been set |
| 100 * A nonzero error number | 92 * A nonzero error number |
| 101 */ | 93 */ |
| 102 | 94 |
| 103 NSS_EXTERN NSSError | 95 NSS_EXTERN NSSError NSS_GetError(void); |
| 104 NSS_GetError | |
| 105 ( | |
| 106 void | |
| 107 ); | |
| 108 | 96 |
| 109 extern const NSSError NSS_ERROR_NO_ERROR; | 97 extern const NSSError NSS_ERROR_NO_ERROR; |
| 110 | 98 |
| 111 /* | 99 /* |
| 112 * NSS_GetErrorStack | 100 * NSS_GetErrorStack |
| 113 * | 101 * |
| 114 * This routine returns a pointer to an array of NSSError values, | 102 * This routine returns a pointer to an array of NSSError values, |
| 115 * containingthe entire sequence or "stack" of errors set by the most | 103 * containingthe entire sequence or "stack" of errors set by the most |
| 116 * recent NSS library routine called by the same thread calling this | 104 * recent NSS library routine called by the same thread calling this |
| 117 * routine. NOTE: the caller DOES NOT OWN the memory pointed to by | 105 * routine. NOTE: the caller DOES NOT OWN the memory pointed to by |
| 118 * the return value. The pointer will remain valid until the calling | 106 * the return value. The pointer will remain valid until the calling |
| 119 * thread calls another NSS routine. The lowest-level (most specific) | 107 * thread calls another NSS routine. The lowest-level (most specific) |
| 120 * error is first in the array, and the highest-level is last. The | 108 * error is first in the array, and the highest-level is last. The |
| 121 * array is zero-terminated. This routine may return NULL upon error; | 109 * array is zero-terminated. This routine may return NULL upon error; |
| 122 * this indicates a low-memory situation. | 110 * this indicates a low-memory situation. |
| 123 * | 111 * |
| 124 * Return value: | 112 * Return value: |
| 125 * NULL upon error, which is an implied NSS_ERROR_NO_MEMORY | 113 * NULL upon error, which is an implied NSS_ERROR_NO_MEMORY |
| 126 * A NON-caller-owned pointer to an array of NSSError values | 114 * A NON-caller-owned pointer to an array of NSSError values |
| 127 */ | 115 */ |
| 128 | 116 |
| 129 NSS_EXTERN NSSError * | 117 NSS_EXTERN NSSError *NSS_GetErrorStack(void); |
| 130 NSS_GetErrorStack | |
| 131 ( | |
| 132 void | |
| 133 ); | |
| 134 | 118 |
| 135 /* | 119 /* |
| 136 * NSS_ZNEW | 120 * NSS_ZNEW |
| 137 * | 121 * |
| 138 * This preprocessor macro will allocate memory for a new object | 122 * This preprocessor macro will allocate memory for a new object |
| 139 * of the specified type with nss_ZAlloc, and will cast the | 123 * of the specified type with nss_ZAlloc, and will cast the |
| 140 * return value appropriately. If the optional arena argument is | 124 * return value appropriately. If the optional arena argument is |
| 141 * non-null, the memory will be obtained from that arena; otherwise, | 125 * non-null, the memory will be obtained from that arena; otherwise, |
| 142 * the memory will be obtained from the heap. This routine may | 126 * the memory will be obtained from the heap. This routine may |
| 143 * return NULL upon error, in which case it will have set an error | 127 * return NULL upon error, in which case it will have set an error |
| 144 * upon the error stack. | 128 * upon the error stack. |
| 145 * | 129 * |
| 146 * The error may be one of the following values: | 130 * The error may be one of the following values: |
| 147 * NSS_ERROR_INVALID_ARENA | 131 * NSS_ERROR_INVALID_ARENA |
| 148 * NSS_ERROR_NO_MEMORY | 132 * NSS_ERROR_NO_MEMORY |
| 149 * | 133 * |
| 150 * Return value: | 134 * Return value: |
| 151 * NULL upon error | 135 * NULL upon error |
| 152 * A pointer to the new segment of zeroed memory | 136 * A pointer to the new segment of zeroed memory |
| 153 */ | 137 */ |
| 154 | 138 |
| 155 /* The following line exceeds 72 characters, but emacs barfs if we split it. */ | |
| 156 #define NSS_ZNEW(arenaOpt, type) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type))) | 139 #define NSS_ZNEW(arenaOpt, type) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type))) |
| 157 | 140 |
| 158 /* | 141 /* |
| 159 * NSS_ZNEWARRAY | 142 * NSS_ZNEWARRAY |
| 160 * | 143 * |
| 161 * This preprocessor macro will allocate memory for an array of | 144 * This preprocessor macro will allocate memory for an array of |
| 162 * new objects, and will cast the return value appropriately. | 145 * new objects, and will cast the return value appropriately. |
| 163 * If the optional arena argument is non-null, the memory will | 146 * If the optional arena argument is non-null, the memory will |
| 164 * be obtained from that arena; otherwise, the memory will be | 147 * be obtained from that arena; otherwise, the memory will be |
| 165 * obtained from the heap. This routine may return NULL upon | 148 * obtained from the heap. This routine may return NULL upon |
| 166 * error, in which case it will have set an error upon the error | 149 * error, in which case it will have set an error upon the error |
| 167 * stack. The array size may be specified as zero. | 150 * stack. The array size may be specified as zero. |
| 168 * | 151 * |
| 169 * The error may be one of the following values: | 152 * The error may be one of the following values: |
| 170 * NSS_ERROR_INVALID_ARENA | 153 * NSS_ERROR_INVALID_ARENA |
| 171 * NSS_ERROR_NO_MEMORY | 154 * NSS_ERROR_NO_MEMORY |
| 172 * | 155 * |
| 173 * Return value: | 156 * Return value: |
| 174 * NULL upon error | 157 * NULL upon error |
| 175 * A pointer to the new segment of zeroed memory | 158 * A pointer to the new segment of zeroed memory |
| 176 */ | 159 */ |
| 177 | 160 |
| 178 /* The following line exceeds 72 characters, but emacs barfs if we split it. */ | 161 #define NSS_ZNEWARRAY(arenaOpt, type, quantity) \ |
| 179 #define NSS_ZNEWARRAY(arenaOpt, type, quantity) ((type *)NSS_ZAlloc((arenaOpt),
sizeof(type) * (quantity))) | 162 ((type *)NSS_ZAlloc((arenaOpt), sizeof(type) * (quantity))) |
| 180 | |
| 181 | 163 |
| 182 /* | 164 /* |
| 183 * NSS_ZAlloc | 165 * NSS_ZAlloc |
| 184 * | 166 * |
| 185 * This routine allocates and zeroes a section of memory of the | 167 * This routine allocates and zeroes a section of memory of the |
| 186 * size, and returns to the caller a pointer to that memory. If | 168 * size, and returns to the caller a pointer to that memory. If |
| 187 * the optional arena argument is non-null, the memory will be | 169 * the optional arena argument is non-null, the memory will be |
| 188 * obtained from that arena; otherwise, the memory will be obtained | 170 * obtained from that arena; otherwise, the memory will be obtained |
| 189 * from the heap. This routine may return NULL upon error, in | 171 * from the heap. This routine may return NULL upon error, in |
| 190 * which case it will have set an error upon the error stack. The | 172 * which case it will have set an error upon the error stack. The |
| 191 * value specified for size may be zero; in which case a valid | 173 * value specified for size may be zero; in which case a valid |
| 192 * zero-length block of memory will be allocated. This block may | 174 * zero-length block of memory will be allocated. This block may |
| 193 * be expanded by calling NSS_ZRealloc. | 175 * be expanded by calling NSS_ZRealloc. |
| 194 * | 176 * |
| 195 * The error may be one of the following values: | 177 * The error may be one of the following values: |
| 196 * NSS_ERROR_INVALID_ARENA | 178 * NSS_ERROR_INVALID_ARENA |
| 197 * NSS_ERROR_NO_MEMORY | 179 * NSS_ERROR_NO_MEMORY |
| 198 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | 180 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
| 199 * | 181 * |
| 200 * Return value: | 182 * Return value: |
| 201 * NULL upon error | 183 * NULL upon error |
| 202 * A pointer to the new segment of zeroed memory | 184 * A pointer to the new segment of zeroed memory |
| 203 */ | 185 */ |
| 204 | 186 |
| 205 NSS_EXTERN void * | 187 NSS_EXTERN void *NSS_ZAlloc(NSSArena *arenaOpt, PRUint32 size); |
| 206 NSS_ZAlloc | |
| 207 ( | |
| 208 NSSArena *arenaOpt, | |
| 209 PRUint32 size | |
| 210 ); | |
| 211 | 188 |
| 212 /* | 189 /* |
| 213 * NSS_ZRealloc | 190 * NSS_ZRealloc |
| 214 * | 191 * |
| 215 * This routine reallocates a block of memory obtained by calling | 192 * This routine reallocates a block of memory obtained by calling |
| 216 * nss_ZAlloc or nss_ZRealloc. The portion of memory | 193 * nss_ZAlloc or nss_ZRealloc. The portion of memory |
| 217 * between the new and old sizes -- which is either being newly | 194 * between the new and old sizes -- which is either being newly |
| 218 * obtained or released -- is in either case zeroed. This routine | 195 * obtained or released -- is in either case zeroed. This routine |
| 219 * may return NULL upon failure, in which case it will have placed | 196 * may return NULL upon failure, in which case it will have placed |
| 220 * an error on the error stack. | 197 * an error on the error stack. |
| 221 * | 198 * |
| 222 * The error may be one of the following values: | 199 * The error may be one of the following values: |
| 223 * NSS_ERROR_INVALID_POINTER | 200 * NSS_ERROR_INVALID_POINTER |
| 224 * NSS_ERROR_NO_MEMORY | 201 * NSS_ERROR_NO_MEMORY |
| 225 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD | 202 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD |
| 226 * | 203 * |
| 227 * Return value: | 204 * Return value: |
| 228 * NULL upon error | 205 * NULL upon error |
| 229 * A pointer to the replacement segment of memory | 206 * A pointer to the replacement segment of memory |
| 230 */ | 207 */ |
| 231 | 208 |
| 232 NSS_EXTERN void * | 209 NSS_EXTERN void *NSS_ZRealloc(void *pointer, PRUint32 newSize); |
| 233 NSS_ZRealloc | |
| 234 ( | |
| 235 void *pointer, | |
| 236 PRUint32 newSize | |
| 237 ); | |
| 238 | |
| 239 | 210 |
| 240 /* | 211 /* |
| 241 * NSS_ZFreeIf | 212 * NSS_ZFreeIf |
| 242 * | 213 * |
| 243 * If the specified pointer is non-null, then the region of memory | 214 * If the specified pointer is non-null, then the region of memory |
| 244 * to which it points -- which must have been allocated with | 215 * to which it points -- which must have been allocated with |
| 245 * nss_ZAlloc -- will be zeroed and released. This routine | 216 * nss_ZAlloc -- will be zeroed and released. This routine |
| 246 * returns a PRStatus value; if successful, it will return PR_SUCCESS. | 217 * returns a PRStatus value; if successful, it will return PR_SUCCESS. |
| 247 * If unsuccessful, it will set an error on the error stack and return | 218 * If unsuccessful, it will set an error on the error stack and return |
| 248 * PR_FAILURE. | 219 * PR_FAILURE. |
| 249 * | 220 * |
| 250 * The error may be one of the following values: | 221 * The error may be one of the following values: |
| 251 * NSS_ERROR_INVALID_POINTER | 222 * NSS_ERROR_INVALID_POINTER |
| 252 * | 223 * |
| 253 * Return value: | 224 * Return value: |
| 254 * PR_SUCCESS | 225 * PR_SUCCESS |
| 255 * PR_FAILURE | 226 * PR_FAILURE |
| 256 */ | 227 */ |
| 257 | 228 |
| 258 NSS_EXTERN PRStatus | 229 NSS_EXTERN PRStatus NSS_ZFreeIf(void *pointer); |
| 259 NSS_ZFreeIf | |
| 260 ( | |
| 261 void *pointer | |
| 262 ); | |
| 263 | 230 |
| 264 PR_END_EXTERN_C | 231 PR_END_EXTERN_C |
| 265 | 232 |
| 266 #endif /* NSSBASE_H */ | 233 #endif /* NSSBASE_H */ |
| OLD | NEW |