security/nss/lib/base/base.h

Thu, 22 Jan 2015 13:21:57 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Thu, 22 Jan 2015 13:21:57 +0100
branch
TOR_BUG_9701
changeset 15
b8a032363ba2
permissions
-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0 1 /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0 2 * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0 4
michael@0 5 #ifndef BASE_H
michael@0 6 #define BASE_H
michael@0 7
michael@0 8 /*
michael@0 9 * base.h
michael@0 10 *
michael@0 11 * This header file contains basic prototypes and preprocessor
michael@0 12 * definitions used throughout nss but not available publicly.
michael@0 13 */
michael@0 14
michael@0 15 #ifndef BASET_H
michael@0 16 #include "baset.h"
michael@0 17 #endif /* BASET_H */
michael@0 18
michael@0 19 #ifndef NSSBASE_H
michael@0 20 #include "nssbase.h"
michael@0 21 #endif /* NSSBASE_H */
michael@0 22
michael@0 23 #include "plhash.h"
michael@0 24
michael@0 25 PR_BEGIN_EXTERN_C
michael@0 26
michael@0 27 /*
michael@0 28 * NSSArena
michael@0 29 *
michael@0 30 * The nonpublic methods relating to this type are:
michael@0 31 *
michael@0 32 * nssArena_Create -- constructor
michael@0 33 * nssArena_Destroy
michael@0 34 * nssArena_Mark
michael@0 35 * nssArena_Release
michael@0 36 * nssArena_Unmark
michael@0 37 *
michael@0 38 * nss_ZAlloc
michael@0 39 * nss_ZFreeIf
michael@0 40 * nss_ZRealloc
michael@0 41 *
michael@0 42 * Additionally, there are some preprocessor macros:
michael@0 43 *
michael@0 44 * nss_ZNEW
michael@0 45 * nss_ZNEWARRAY
michael@0 46 *
michael@0 47 * In debug builds, the following calls are available:
michael@0 48 *
michael@0 49 * nssArena_verifyPointer
michael@0 50 * nssArena_registerDestructor
michael@0 51 * nssArena_deregisterDestructor
michael@0 52 *
michael@0 53 * The following preprocessor macro is also always available:
michael@0 54 *
michael@0 55 * nssArena_VERIFYPOINTER
michael@0 56 *
michael@0 57 * A constant PLHashAllocOps structure is available for users
michael@0 58 * of the NSPL PLHashTable routines.
michael@0 59 *
michael@0 60 * nssArenaHashAllocOps
michael@0 61 */
michael@0 62
michael@0 63 /*
michael@0 64 * nssArena_Create
michael@0 65 *
michael@0 66 * This routine creates a new memory arena. This routine may return
michael@0 67 * NULL upon error, in which case it will have set an error on the
michael@0 68 * error stack.
michael@0 69 *
michael@0 70 * The error may be one of the following values:
michael@0 71 * NSS_ERROR_NO_MEMORY
michael@0 72 *
michael@0 73 * Return value:
michael@0 74 * NULL upon error
michael@0 75 * A pointer to an NSSArena upon success
michael@0 76 */
michael@0 77
michael@0 78 /*
michael@0 79 * XXX fgmr
michael@0 80 * Arenas can be named upon creation; this is mostly of use when
michael@0 81 * debugging. Should we expose that here, allowing an optional
michael@0 82 * "const char *name" argument? Should the public version of this
michael@0 83 * call (NSSArena_Create) have it too?
michael@0 84 */
michael@0 85
michael@0 86 NSS_EXTERN NSSArena *
michael@0 87 nssArena_Create
michael@0 88 (
michael@0 89 void
michael@0 90 );
michael@0 91
michael@0 92 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 93
michael@0 94 /*
michael@0 95 * nssArena_Destroy
michael@0 96 *
michael@0 97 * This routine will destroy the specified arena, freeing all memory
michael@0 98 * allocated from it. This routine returns a PRStatus value; if
michael@0 99 * successful, it will return PR_SUCCESS. If unsuccessful, it will
michael@0 100 * set an error on the error stack and return PR_FAILURE.
michael@0 101 *
michael@0 102 * The error may be one of the following values:
michael@0 103 * NSS_ERROR_INVALID_ARENA
michael@0 104 *
michael@0 105 * Return value:
michael@0 106 * PR_SUCCESS
michael@0 107 * PR_FAILURE
michael@0 108 */
michael@0 109
michael@0 110 NSS_EXTERN PRStatus
michael@0 111 nssArena_Destroy
michael@0 112 (
michael@0 113 NSSArena *arena
michael@0 114 );
michael@0 115
michael@0 116 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 117
michael@0 118 /*
michael@0 119 * nssArena_Mark
michael@0 120 *
michael@0 121 * This routine "marks" the current state of an arena. Space
michael@0 122 * allocated after the arena has been marked can be freed by
michael@0 123 * releasing the arena back to the mark with nssArena_Release,
michael@0 124 * or committed by calling nssArena_Unmark. When successful,
michael@0 125 * this routine returns a valid nssArenaMark pointer. This
michael@0 126 * routine may return NULL upon error, in which case it will
michael@0 127 * have set an error on the error stack.
michael@0 128 *
michael@0 129 * The error may be one of the following values:
michael@0 130 * NSS_ERROR_INVALID_ARENA
michael@0 131 * NSS_ERROR_NO_MEMORY
michael@0 132 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0 133 *
michael@0 134 * Return value:
michael@0 135 * NULL upon failure
michael@0 136 * An nssArenaMark pointer upon success
michael@0 137 */
michael@0 138
michael@0 139 NSS_EXTERN nssArenaMark *
michael@0 140 nssArena_Mark
michael@0 141 (
michael@0 142 NSSArena *arena
michael@0 143 );
michael@0 144
michael@0 145 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 146 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 147 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
michael@0 148
michael@0 149 /*
michael@0 150 * nssArena_Release
michael@0 151 *
michael@0 152 * This routine invalidates and releases all memory allocated from
michael@0 153 * the specified arena after the point at which the specified mark
michael@0 154 * was obtained. This routine returns a PRStatus value; if successful,
michael@0 155 * it will return PR_SUCCESS. If unsuccessful, it will set an error
michael@0 156 * on the error stack and return PR_FAILURE.
michael@0 157 *
michael@0 158 * The error may be one of the following values:
michael@0 159 * NSS_ERROR_INVALID_ARENA
michael@0 160 * NSS_ERROR_INVALID_ARENA_MARK
michael@0 161 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0 162 *
michael@0 163 * Return value:
michael@0 164 * PR_SUCCESS
michael@0 165 * PR_FAILURE
michael@0 166 */
michael@0 167
michael@0 168 NSS_EXTERN PRStatus
michael@0 169 nssArena_Release
michael@0 170 (
michael@0 171 NSSArena *arena,
michael@0 172 nssArenaMark *arenaMark
michael@0 173 );
michael@0 174
michael@0 175 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 176 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
michael@0 177
michael@0 178 /*
michael@0 179 * nssArena_Unmark
michael@0 180 *
michael@0 181 * This routine "commits" the indicated mark and any marks after
michael@0 182 * it, making them unreleasable. Note that any earlier marks can
michael@0 183 * still be released, and such a release will invalidate these
michael@0 184 * later unmarked regions. If an arena is to be safely shared by
michael@0 185 * more than one thread, all marks must be either released or
michael@0 186 * unmarked. This routine returns a PRStatus value; if successful,
michael@0 187 * it will return PR_SUCCESS. If unsuccessful, it will set an error
michael@0 188 * on the error stack and return PR_FAILURE.
michael@0 189 *
michael@0 190 * The error may be one of the following values:
michael@0 191 * NSS_ERROR_INVALID_ARENA
michael@0 192 * NSS_ERROR_INVALID_ARENA_MARK
michael@0 193 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0 194 *
michael@0 195 * Return value:
michael@0 196 * PR_SUCCESS
michael@0 197 * PR_FAILURE
michael@0 198 */
michael@0 199
michael@0 200 NSS_EXTERN PRStatus
michael@0 201 nssArena_Unmark
michael@0 202 (
michael@0 203 NSSArena *arena,
michael@0 204 nssArenaMark *arenaMark
michael@0 205 );
michael@0 206
michael@0 207 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 208 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
michael@0 209 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
michael@0 210
michael@0 211 #ifdef ARENA_DESTRUCTOR_LIST
michael@0 212
michael@0 213 /*
michael@0 214 * nssArena_registerDestructor
michael@0 215 *
michael@0 216 * This routine stores a pointer to a callback and an arbitrary
michael@0 217 * pointer-sized argument in the arena, at the current point in
michael@0 218 * the mark stack. If the arena is destroyed, or an "earlier"
michael@0 219 * mark is released, then this destructor will be called at that
michael@0 220 * time. Note that the destructor will be called with the arena
michael@0 221 * locked, which means the destructor may free memory in that
michael@0 222 * arena, but it may not allocate or cause to be allocated any
michael@0 223 * memory. This callback facility was included to support our
michael@0 224 * debug-version pointer-tracker feature; overuse runs counter to
michael@0 225 * the the original intent of arenas. This routine returns a
michael@0 226 * PRStatus value; if successful, it will return PR_SUCCESS. If
michael@0 227 * unsuccessful, it will set an error on the error stack and
michael@0 228 * return PR_FAILURE.
michael@0 229 *
michael@0 230 * The error may be one of the following values:
michael@0 231 * NSS_ERROR_INVALID_ARENA
michael@0 232 * NSS_ERROR_NO_MEMORY
michael@0 233 *
michael@0 234 * Return value:
michael@0 235 * PR_SUCCESS
michael@0 236 * PR_FAILURE
michael@0 237 */
michael@0 238
michael@0 239 NSS_EXTERN PRStatus
michael@0 240 nssArena_registerDestructor
michael@0 241 (
michael@0 242 NSSArena *arena,
michael@0 243 void (*destructor)(void *argument),
michael@0 244 void *arg
michael@0 245 );
michael@0 246
michael@0 247 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 248 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 249
michael@0 250 /*
michael@0 251 * nssArena_deregisterDestructor
michael@0 252 *
michael@0 253 * This routine will remove the first destructor in the specified
michael@0 254 * arena which has the specified destructor and argument values.
michael@0 255 * The destructor will not be called. This routine returns a
michael@0 256 * PRStatus value; if successful, it will return PR_SUCCESS. If
michael@0 257 * unsuccessful, it will set an error on the error stack and
michael@0 258 * return PR_FAILURE.
michael@0 259 *
michael@0 260 * The error may be one of the following values:
michael@0 261 * NSS_ERROR_INVALID_ARENA
michael@0 262 * NSS_ERROR_NOT_FOUND
michael@0 263 *
michael@0 264 * Return value:
michael@0 265 * PR_SUCCESS
michael@0 266 * PR_FAILURE
michael@0 267 */
michael@0 268
michael@0 269 NSS_EXTERN PRStatus
michael@0 270 nssArena_deregisterDestructor
michael@0 271 (
michael@0 272 NSSArena *arena,
michael@0 273 void (*destructor)(void *argument),
michael@0 274 void *arg
michael@0 275 );
michael@0 276
michael@0 277 extern const NSSError NSS_ERROR_INVALID_ITEM;
michael@0 278 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 279 extern const NSSError NSS_ERROR_NOT_FOUND;
michael@0 280
michael@0 281 #endif /* ARENA_DESTRUCTOR_LIST */
michael@0 282
michael@0 283 /*
michael@0 284 * nss_ZAlloc
michael@0 285 *
michael@0 286 * This routine allocates and zeroes a section of memory of the
michael@0 287 * size, and returns to the caller a pointer to that memory. If
michael@0 288 * the optional arena argument is non-null, the memory will be
michael@0 289 * obtained from that arena; otherwise, the memory will be obtained
michael@0 290 * from the heap. This routine may return NULL upon error, in
michael@0 291 * which case it will have set an error upon the error stack. The
michael@0 292 * value specified for size may be zero; in which case a valid
michael@0 293 * zero-length block of memory will be allocated. This block may
michael@0 294 * be expanded by calling nss_ZRealloc.
michael@0 295 *
michael@0 296 * The error may be one of the following values:
michael@0 297 * NSS_ERROR_INVALID_ARENA
michael@0 298 * NSS_ERROR_NO_MEMORY
michael@0 299 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0 300 *
michael@0 301 * Return value:
michael@0 302 * NULL upon error
michael@0 303 * A pointer to the new segment of zeroed memory
michael@0 304 */
michael@0 305
michael@0 306 NSS_EXTERN void *
michael@0 307 nss_ZAlloc
michael@0 308 (
michael@0 309 NSSArena *arenaOpt,
michael@0 310 PRUint32 size
michael@0 311 );
michael@0 312
michael@0 313 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 314 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 315 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
michael@0 316
michael@0 317 /*
michael@0 318 * nss_ZFreeIf
michael@0 319 *
michael@0 320 * If the specified pointer is non-null, then the region of memory
michael@0 321 * to which it points -- which must have been allocated with
michael@0 322 * nss_ZAlloc -- will be zeroed and released. This routine
michael@0 323 * returns a PRStatus value; if successful, it will return PR_SUCCESS.
michael@0 324 * If unsuccessful, it will set an error on the error stack and return
michael@0 325 * PR_FAILURE.
michael@0 326 *
michael@0 327 * The error may be one of the following values:
michael@0 328 * NSS_ERROR_INVALID_POINTER
michael@0 329 *
michael@0 330 * Return value:
michael@0 331 * PR_SUCCESS
michael@0 332 * PR_FAILURE
michael@0 333 */
michael@0 334
michael@0 335 NSS_EXTERN PRStatus
michael@0 336 nss_ZFreeIf
michael@0 337 (
michael@0 338 void *pointer
michael@0 339 );
michael@0 340
michael@0 341 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 342
michael@0 343 /*
michael@0 344 * nss_ZRealloc
michael@0 345 *
michael@0 346 * This routine reallocates a block of memory obtained by calling
michael@0 347 * nss_ZAlloc or nss_ZRealloc. The portion of memory
michael@0 348 * between the new and old sizes -- which is either being newly
michael@0 349 * obtained or released -- is in either case zeroed. This routine
michael@0 350 * may return NULL upon failure, in which case it will have placed
michael@0 351 * an error on the error stack.
michael@0 352 *
michael@0 353 * The error may be one of the following values:
michael@0 354 * NSS_ERROR_INVALID_POINTER
michael@0 355 * NSS_ERROR_NO_MEMORY
michael@0 356 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0 357 *
michael@0 358 * Return value:
michael@0 359 * NULL upon error
michael@0 360 * A pointer to the replacement segment of memory
michael@0 361 */
michael@0 362
michael@0 363 NSS_EXTERN void *
michael@0 364 nss_ZRealloc
michael@0 365 (
michael@0 366 void *pointer,
michael@0 367 PRUint32 newSize
michael@0 368 );
michael@0 369
michael@0 370 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 371 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 372 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
michael@0 373
michael@0 374 /*
michael@0 375 * nss_ZNEW
michael@0 376 *
michael@0 377 * This preprocessor macro will allocate memory for a new object
michael@0 378 * of the specified type with nss_ZAlloc, and will cast the
michael@0 379 * return value appropriately. If the optional arena argument is
michael@0 380 * non-null, the memory will be obtained from that arena; otherwise,
michael@0 381 * the memory will be obtained from the heap. This routine may
michael@0 382 * return NULL upon error, in which case it will have set an error
michael@0 383 * upon the error stack.
michael@0 384 *
michael@0 385 * The error may be one of the following values:
michael@0 386 * NSS_ERROR_INVALID_ARENA
michael@0 387 * NSS_ERROR_NO_MEMORY
michael@0 388 *
michael@0 389 * Return value:
michael@0 390 * NULL upon error
michael@0 391 * A pointer to the new segment of zeroed memory
michael@0 392 */
michael@0 393
michael@0 394 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
michael@0 395 #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type)))
michael@0 396
michael@0 397 /*
michael@0 398 * nss_ZNEWARRAY
michael@0 399 *
michael@0 400 * This preprocessor macro will allocate memory for an array of
michael@0 401 * new objects, and will cast the return value appropriately.
michael@0 402 * If the optional arena argument is non-null, the memory will
michael@0 403 * be obtained from that arena; otherwise, the memory will be
michael@0 404 * obtained from the heap. This routine may return NULL upon
michael@0 405 * error, in which case it will have set an error upon the error
michael@0 406 * stack. The array size may be specified as zero.
michael@0 407 *
michael@0 408 * The error may be one of the following values:
michael@0 409 * NSS_ERROR_INVALID_ARENA
michael@0 410 * NSS_ERROR_NO_MEMORY
michael@0 411 *
michael@0 412 * Return value:
michael@0 413 * NULL upon error
michael@0 414 * A pointer to the new segment of zeroed memory
michael@0 415 */
michael@0 416
michael@0 417 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
michael@0 418 #define nss_ZNEWARRAY(arenaOpt, type, quantity) ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
michael@0 419
michael@0 420 /*
michael@0 421 * nss_ZREALLOCARRAY
michael@0 422 *
michael@0 423 * This preprocessor macro will reallocate memory for an array of
michael@0 424 * new objects, and will cast the return value appropriately.
michael@0 425 * This routine may return NULL upon error, in which case it will
michael@0 426 * have set an error upon the error stack.
michael@0 427 *
michael@0 428 * The error may be one of the following values:
michael@0 429 * NSS_ERROR_INVALID_POINTER
michael@0 430 * NSS_ERROR_NO_MEMORY
michael@0 431 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
michael@0 432 *
michael@0 433 * Return value:
michael@0 434 * NULL upon error
michael@0 435 * A pointer to the replacement segment of memory
michael@0 436 */
michael@0 437 #define nss_ZREALLOCARRAY(p, type, quantity) ((type *)nss_ZRealloc((p), sizeof(type) * (quantity)))
michael@0 438
michael@0 439 /*
michael@0 440 * nssArena_verifyPointer
michael@0 441 *
michael@0 442 * This method is only present in debug builds.
michael@0 443 *
michael@0 444 * If the specified pointer is a valid pointer to an NSSArena object,
michael@0 445 * this routine will return PR_SUCCESS. Otherwise, it will put an
michael@0 446 * error on the error stack and return PR_FAILURE.
michael@0 447 *
michael@0 448 * The error may be one of the following values:
michael@0 449 * NSS_ERROR_INVALID_ARENA
michael@0 450 *
michael@0 451 * Return value:
michael@0 452 * PR_SUCCESS if the pointer is valid
michael@0 453 * PR_FAILURE if it isn't
michael@0 454 */
michael@0 455
michael@0 456 #ifdef DEBUG
michael@0 457 NSS_EXTERN PRStatus
michael@0 458 nssArena_verifyPointer
michael@0 459 (
michael@0 460 const NSSArena *arena
michael@0 461 );
michael@0 462
michael@0 463 extern const NSSError NSS_ERROR_INVALID_ARENA;
michael@0 464 #endif /* DEBUG */
michael@0 465
michael@0 466 /*
michael@0 467 * nssArena_VERIFYPOINTER
michael@0 468 *
michael@0 469 * This macro is always available. In debug builds it will call
michael@0 470 * nssArena_verifyPointer; in non-debug builds, it will merely
michael@0 471 * check that the pointer is not null. Note that in non-debug
michael@0 472 * builds it cannot place an error on the error stack.
michael@0 473 *
michael@0 474 * Return value:
michael@0 475 * PR_SUCCESS if the pointer is valid
michael@0 476 * PR_FAILURE if it isn't
michael@0 477 */
michael@0 478
michael@0 479 #ifdef DEBUG
michael@0 480 #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p)
michael@0 481 #else /* DEBUG */
michael@0 482 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
michael@0 483 #define nssArena_VERIFYPOINTER(p) (((NSSArena *)NULL == (p))?PR_FAILURE:PR_SUCCESS)
michael@0 484 #endif /* DEBUG */
michael@0 485
michael@0 486 /*
michael@0 487 * Private function to be called by NSS_Shutdown to cleanup nssArena
michael@0 488 * bookkeeping.
michael@0 489 */
michael@0 490 extern PRStatus
michael@0 491 nssArena_Shutdown(void);
michael@0 492
michael@0 493 /*
michael@0 494 * nssArenaHashAllocOps
michael@0 495 *
michael@0 496 * This constant structure contains allocation callbacks designed for
michael@0 497 * use with the NSPL routine PL_NewHashTable. For example:
michael@0 498 *
michael@0 499 * NSSArena *hashTableArena = nssArena_Create();
michael@0 500 * PLHashTable *t = PL_NewHashTable(n, hasher, key_compare,
michael@0 501 * value_compare, nssArenaHashAllocOps, hashTableArena);
michael@0 502 */
michael@0 503
michael@0 504 NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps;
michael@0 505
michael@0 506 /*
michael@0 507 * The error stack
michael@0 508 *
michael@0 509 * The nonpublic methods relating to the error stack are:
michael@0 510 *
michael@0 511 * nss_SetError
michael@0 512 * nss_ClearErrorStack
michael@0 513 */
michael@0 514
michael@0 515 /*
michael@0 516 * nss_SetError
michael@0 517 *
michael@0 518 * This routine places a new error code on the top of the calling
michael@0 519 * thread's error stack. Calling this routine wiht an error code
michael@0 520 * of zero will clear the error stack.
michael@0 521 */
michael@0 522
michael@0 523 NSS_EXTERN void
michael@0 524 nss_SetError
michael@0 525 (
michael@0 526 PRUint32 error
michael@0 527 );
michael@0 528
michael@0 529 /*
michael@0 530 * nss_ClearErrorStack
michael@0 531 *
michael@0 532 * This routine clears the calling thread's error stack.
michael@0 533 */
michael@0 534
michael@0 535 NSS_EXTERN void
michael@0 536 nss_ClearErrorStack
michael@0 537 (
michael@0 538 void
michael@0 539 );
michael@0 540
michael@0 541 /*
michael@0 542 * nss_DestroyErrorStack
michael@0 543 *
michael@0 544 * This routine frees the calling thread's error stack.
michael@0 545 */
michael@0 546
michael@0 547 NSS_EXTERN void
michael@0 548 nss_DestroyErrorStack
michael@0 549 (
michael@0 550 void
michael@0 551 );
michael@0 552
michael@0 553 /*
michael@0 554 * NSSItem
michael@0 555 *
michael@0 556 * nssItem_Create
michael@0 557 * nssItem_Duplicate
michael@0 558 * nssItem_Equal
michael@0 559 */
michael@0 560
michael@0 561 NSS_EXTERN NSSItem *
michael@0 562 nssItem_Create
michael@0 563 (
michael@0 564 NSSArena *arenaOpt,
michael@0 565 NSSItem *rvOpt,
michael@0 566 PRUint32 length,
michael@0 567 const void *data
michael@0 568 );
michael@0 569
michael@0 570 NSS_EXTERN void
michael@0 571 nssItem_Destroy
michael@0 572 (
michael@0 573 NSSItem *item
michael@0 574 );
michael@0 575
michael@0 576 NSS_EXTERN NSSItem *
michael@0 577 nssItem_Duplicate
michael@0 578 (
michael@0 579 NSSItem *obj,
michael@0 580 NSSArena *arenaOpt,
michael@0 581 NSSItem *rvOpt
michael@0 582 );
michael@0 583
michael@0 584 NSS_EXTERN PRBool
michael@0 585 nssItem_Equal
michael@0 586 (
michael@0 587 const NSSItem *one,
michael@0 588 const NSSItem *two,
michael@0 589 PRStatus *statusOpt
michael@0 590 );
michael@0 591
michael@0 592 /*
michael@0 593 * NSSUTF8
michael@0 594 *
michael@0 595 * nssUTF8_CaseIgnoreMatch
michael@0 596 * nssUTF8_Duplicate
michael@0 597 * nssUTF8_Size
michael@0 598 * nssUTF8_Length
michael@0 599 * nssUTF8_CopyIntoFixedBuffer
michael@0 600 */
michael@0 601
michael@0 602 /*
michael@0 603 * nssUTF8_CaseIgnoreMatch
michael@0 604 *
michael@0 605 * Returns true if the two UTF8-encoded strings pointed to by the
michael@0 606 * two specified NSSUTF8 pointers differ only in typcase.
michael@0 607 *
michael@0 608 * The error may be one of the following values:
michael@0 609 * NSS_ERROR_INVALID_POINTER
michael@0 610 *
michael@0 611 * Return value:
michael@0 612 * PR_TRUE if the strings match, ignoring case
michael@0 613 * PR_FALSE if they don't
michael@0 614 * PR_FALSE upon error
michael@0 615 */
michael@0 616
michael@0 617 NSS_EXTERN PRBool
michael@0 618 nssUTF8_CaseIgnoreMatch
michael@0 619 (
michael@0 620 const NSSUTF8 *a,
michael@0 621 const NSSUTF8 *b,
michael@0 622 PRStatus *statusOpt
michael@0 623 );
michael@0 624
michael@0 625 /*
michael@0 626 * nssUTF8_Duplicate
michael@0 627 *
michael@0 628 * This routine duplicates the UTF8-encoded string pointed to by the
michael@0 629 * specified NSSUTF8 pointer. If the optional arenaOpt argument is
michael@0 630 * not null, the memory required will be obtained from that arena;
michael@0 631 * otherwise, the memory required will be obtained from the heap.
michael@0 632 * A pointer to the new string will be returned. In case of error,
michael@0 633 * an error will be placed on the error stack and NULL will be
michael@0 634 * returned.
michael@0 635 *
michael@0 636 * The error may be one of the following values:
michael@0 637 * NSS_ERROR_INVALID_POINTER
michael@0 638 * NSS_ERROR_INVALID_ARENA
michael@0 639 * NSS_ERROR_NO_MEMORY
michael@0 640 */
michael@0 641
michael@0 642 NSS_EXTERN NSSUTF8 *
michael@0 643 nssUTF8_Duplicate
michael@0 644 (
michael@0 645 const NSSUTF8 *s,
michael@0 646 NSSArena *arenaOpt
michael@0 647 );
michael@0 648
michael@0 649 /*
michael@0 650 * nssUTF8_PrintableMatch
michael@0 651 *
michael@0 652 * Returns true if the two Printable strings pointed to by the
michael@0 653 * two specified NSSUTF8 pointers match when compared with the
michael@0 654 * rules for Printable String (leading and trailing spaces are
michael@0 655 * disregarded, extents of whitespace match irregardless of length,
michael@0 656 * and case is not significant), then PR_TRUE will be returned.
michael@0 657 * Otherwise, PR_FALSE will be returned. Upon failure, PR_FALSE
michael@0 658 * will be returned. If the optional statusOpt argument is not
michael@0 659 * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that
michael@0 660 * location.
michael@0 661 *
michael@0 662 * The error may be one of the following values:
michael@0 663 * NSS_ERROR_INVALID_POINTER
michael@0 664 *
michael@0 665 * Return value:
michael@0 666 * PR_TRUE if the strings match, ignoring case
michael@0 667 * PR_FALSE if they don't
michael@0 668 * PR_FALSE upon error
michael@0 669 */
michael@0 670
michael@0 671 NSS_EXTERN PRBool
michael@0 672 nssUTF8_PrintableMatch
michael@0 673 (
michael@0 674 const NSSUTF8 *a,
michael@0 675 const NSSUTF8 *b,
michael@0 676 PRStatus *statusOpt
michael@0 677 );
michael@0 678
michael@0 679 /*
michael@0 680 * nssUTF8_Size
michael@0 681 *
michael@0 682 * This routine returns the length in bytes (including the terminating
michael@0 683 * null) of the UTF8-encoded string pointed to by the specified
michael@0 684 * NSSUTF8 pointer. Zero is returned on error.
michael@0 685 *
michael@0 686 * The error may be one of the following values:
michael@0 687 * NSS_ERROR_INVALID_POINTER
michael@0 688 * NSS_ERROR_VALUE_TOO_LARGE
michael@0 689 *
michael@0 690 * Return value:
michael@0 691 * nonzero size of the string
michael@0 692 * 0 on error
michael@0 693 */
michael@0 694
michael@0 695 NSS_EXTERN PRUint32
michael@0 696 nssUTF8_Size
michael@0 697 (
michael@0 698 const NSSUTF8 *s,
michael@0 699 PRStatus *statusOpt
michael@0 700 );
michael@0 701
michael@0 702 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 703 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
michael@0 704
michael@0 705 /*
michael@0 706 * nssUTF8_Length
michael@0 707 *
michael@0 708 * This routine returns the length in characters (not including the
michael@0 709 * terminating null) of the UTF8-encoded string pointed to by the
michael@0 710 * specified NSSUTF8 pointer.
michael@0 711 *
michael@0 712 * The error may be one of the following values:
michael@0 713 * NSS_ERROR_INVALID_POINTER
michael@0 714 * NSS_ERROR_VALUE_TOO_LARGE
michael@0 715 * NSS_ERROR_INVALID_STRING
michael@0 716 *
michael@0 717 * Return value:
michael@0 718 * length of the string (which may be zero)
michael@0 719 * 0 on error
michael@0 720 */
michael@0 721
michael@0 722 NSS_EXTERN PRUint32
michael@0 723 nssUTF8_Length
michael@0 724 (
michael@0 725 const NSSUTF8 *s,
michael@0 726 PRStatus *statusOpt
michael@0 727 );
michael@0 728
michael@0 729 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 730 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
michael@0 731 extern const NSSError NSS_ERROR_INVALID_STRING;
michael@0 732
michael@0 733 /*
michael@0 734 * nssUTF8_Create
michael@0 735 *
michael@0 736 * This routine creates a UTF8 string from a string in some other
michael@0 737 * format. Some types of string may include embedded null characters,
michael@0 738 * so for them the length parameter must be used. For string types
michael@0 739 * that are null-terminated, the length parameter is optional; if it
michael@0 740 * is zero, it will be ignored. If the optional arena argument is
michael@0 741 * non-null, the memory used for the new string will be obtained from
michael@0 742 * that arena, otherwise it will be obtained from the heap. This
michael@0 743 * routine may return NULL upon error, in which case it will have
michael@0 744 * placed an error on the error stack.
michael@0 745 *
michael@0 746 * The error may be one of the following:
michael@0 747 * NSS_ERROR_INVALID_POINTER
michael@0 748 * NSS_ERROR_NO_MEMORY
michael@0 749 * NSS_ERROR_UNSUPPORTED_TYPE
michael@0 750 *
michael@0 751 * Return value:
michael@0 752 * NULL upon error
michael@0 753 * A non-null pointer to a new UTF8 string otherwise
michael@0 754 */
michael@0 755
michael@0 756 NSS_EXTERN NSSUTF8 *
michael@0 757 nssUTF8_Create
michael@0 758 (
michael@0 759 NSSArena *arenaOpt,
michael@0 760 nssStringType type,
michael@0 761 const void *inputString,
michael@0 762 PRUint32 size /* in bytes, not characters */
michael@0 763 );
michael@0 764
michael@0 765 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 766 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 767 extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE;
michael@0 768
michael@0 769 NSS_EXTERN NSSItem *
michael@0 770 nssUTF8_GetEncoding
michael@0 771 (
michael@0 772 NSSArena *arenaOpt,
michael@0 773 NSSItem *rvOpt,
michael@0 774 nssStringType type,
michael@0 775 NSSUTF8 *string
michael@0 776 );
michael@0 777
michael@0 778 /*
michael@0 779 * nssUTF8_CopyIntoFixedBuffer
michael@0 780 *
michael@0 781 * This will copy a UTF8 string into a fixed-length buffer, making
michael@0 782 * sure that the all characters are valid. Any remaining space will
michael@0 783 * be padded with the specified ASCII character, typically either
michael@0 784 * null or space.
michael@0 785 *
michael@0 786 * Blah, blah, blah.
michael@0 787 */
michael@0 788
michael@0 789 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 790 extern const NSSError NSS_ERROR_INVALID_ARGUMENT;
michael@0 791
michael@0 792 NSS_EXTERN PRStatus
michael@0 793 nssUTF8_CopyIntoFixedBuffer
michael@0 794 (
michael@0 795 NSSUTF8 *string,
michael@0 796 char *buffer,
michael@0 797 PRUint32 bufferSize,
michael@0 798 char pad
michael@0 799 );
michael@0 800
michael@0 801 /*
michael@0 802 * nssUTF8_Equal
michael@0 803 *
michael@0 804 */
michael@0 805
michael@0 806 NSS_EXTERN PRBool
michael@0 807 nssUTF8_Equal
michael@0 808 (
michael@0 809 const NSSUTF8 *a,
michael@0 810 const NSSUTF8 *b,
michael@0 811 PRStatus *statusOpt
michael@0 812 );
michael@0 813
michael@0 814 /*
michael@0 815 * nssList
michael@0 816 *
michael@0 817 * The goal is to provide a simple, optionally threadsafe, linked list
michael@0 818 * class. Since NSS did not seem to use the circularity of PRCList
michael@0 819 * much before, this provides a list that appears to be a linear,
michael@0 820 * NULL-terminated list.
michael@0 821 */
michael@0 822
michael@0 823 /*
michael@0 824 * nssList_Create
michael@0 825 *
michael@0 826 * If threadsafe is true, the list will be locked during modifications
michael@0 827 * and traversals.
michael@0 828 */
michael@0 829 NSS_EXTERN nssList *
michael@0 830 nssList_Create
michael@0 831 (
michael@0 832 NSSArena *arenaOpt,
michael@0 833 PRBool threadSafe
michael@0 834 );
michael@0 835
michael@0 836 /*
michael@0 837 * nssList_Destroy
michael@0 838 */
michael@0 839 NSS_EXTERN PRStatus
michael@0 840 nssList_Destroy
michael@0 841 (
michael@0 842 nssList *list
michael@0 843 );
michael@0 844
michael@0 845 NSS_EXTERN void
michael@0 846 nssList_Clear
michael@0 847 (
michael@0 848 nssList *list,
michael@0 849 nssListElementDestructorFunc destructor
michael@0 850 );
michael@0 851
michael@0 852 /*
michael@0 853 * nssList_SetCompareFunction
michael@0 854 *
michael@0 855 * By default, two list elements will be compared by comparing their
michael@0 856 * data pointers. By setting this function, the user can control
michael@0 857 * how elements are compared.
michael@0 858 */
michael@0 859 NSS_EXTERN void
michael@0 860 nssList_SetCompareFunction
michael@0 861 (
michael@0 862 nssList *list,
michael@0 863 nssListCompareFunc compareFunc
michael@0 864 );
michael@0 865
michael@0 866 /*
michael@0 867 * nssList_SetSortFunction
michael@0 868 *
michael@0 869 * Sort function to use for an ordered list.
michael@0 870 */
michael@0 871 NSS_EXTERN void
michael@0 872 nssList_SetSortFunction
michael@0 873 (
michael@0 874 nssList *list,
michael@0 875 nssListSortFunc sortFunc
michael@0 876 );
michael@0 877
michael@0 878 /*
michael@0 879 * nssList_Add
michael@0 880 */
michael@0 881 NSS_EXTERN PRStatus
michael@0 882 nssList_Add
michael@0 883 (
michael@0 884 nssList *list,
michael@0 885 void *data
michael@0 886 );
michael@0 887
michael@0 888 /*
michael@0 889 * nssList_AddUnique
michael@0 890 *
michael@0 891 * This will use the compare function to see if the element is already
michael@0 892 * in the list.
michael@0 893 */
michael@0 894 NSS_EXTERN PRStatus
michael@0 895 nssList_AddUnique
michael@0 896 (
michael@0 897 nssList *list,
michael@0 898 void *data
michael@0 899 );
michael@0 900
michael@0 901 /*
michael@0 902 * nssList_Remove
michael@0 903 *
michael@0 904 * Uses the compare function to locate the element and remove it.
michael@0 905 */
michael@0 906 NSS_EXTERN PRStatus
michael@0 907 nssList_Remove(nssList *list, void *data);
michael@0 908
michael@0 909 /*
michael@0 910 * nssList_Get
michael@0 911 *
michael@0 912 * Uses the compare function to locate an element. Also serves as
michael@0 913 * nssList_Exists.
michael@0 914 */
michael@0 915 NSS_EXTERN void *
michael@0 916 nssList_Get
michael@0 917 (
michael@0 918 nssList *list,
michael@0 919 void *data
michael@0 920 );
michael@0 921
michael@0 922 /*
michael@0 923 * nssList_Count
michael@0 924 */
michael@0 925 NSS_EXTERN PRUint32
michael@0 926 nssList_Count
michael@0 927 (
michael@0 928 nssList *list
michael@0 929 );
michael@0 930
michael@0 931 /*
michael@0 932 * nssList_GetArray
michael@0 933 *
michael@0 934 * Fill rvArray, up to maxElements, with elements in the list. The
michael@0 935 * array is NULL-terminated, so its allocated size must be maxElements + 1.
michael@0 936 */
michael@0 937 NSS_EXTERN PRStatus
michael@0 938 nssList_GetArray
michael@0 939 (
michael@0 940 nssList *list,
michael@0 941 void **rvArray,
michael@0 942 PRUint32 maxElements
michael@0 943 );
michael@0 944
michael@0 945 /*
michael@0 946 * nssList_CreateIterator
michael@0 947 *
michael@0 948 * Create an iterator for list traversal.
michael@0 949 */
michael@0 950 NSS_EXTERN nssListIterator *
michael@0 951 nssList_CreateIterator
michael@0 952 (
michael@0 953 nssList *list
michael@0 954 );
michael@0 955
michael@0 956 NSS_EXTERN nssList *
michael@0 957 nssList_Clone
michael@0 958 (
michael@0 959 nssList *list
michael@0 960 );
michael@0 961
michael@0 962 /*
michael@0 963 * nssListIterator_Destroy
michael@0 964 */
michael@0 965 NSS_EXTERN void
michael@0 966 nssListIterator_Destroy
michael@0 967 (
michael@0 968 nssListIterator *iter
michael@0 969 );
michael@0 970
michael@0 971 /*
michael@0 972 * nssListIterator_Start
michael@0 973 *
michael@0 974 * Begin a list iteration. After this call, if the list is threadSafe,
michael@0 975 * the list is *locked*.
michael@0 976 */
michael@0 977 NSS_EXTERN void *
michael@0 978 nssListIterator_Start
michael@0 979 (
michael@0 980 nssListIterator *iter
michael@0 981 );
michael@0 982
michael@0 983 /*
michael@0 984 * nssListIterator_Next
michael@0 985 *
michael@0 986 * Continue a list iteration.
michael@0 987 */
michael@0 988 NSS_EXTERN void *
michael@0 989 nssListIterator_Next
michael@0 990 (
michael@0 991 nssListIterator *iter
michael@0 992 );
michael@0 993
michael@0 994 /*
michael@0 995 * nssListIterator_Finish
michael@0 996 *
michael@0 997 * Complete a list iteration. This *must* be called in order for the
michael@0 998 * lock to be released.
michael@0 999 */
michael@0 1000 NSS_EXTERN PRStatus
michael@0 1001 nssListIterator_Finish
michael@0 1002 (
michael@0 1003 nssListIterator *iter
michael@0 1004 );
michael@0 1005
michael@0 1006 /*
michael@0 1007 * nssHash
michael@0 1008 *
michael@0 1009 * nssHash_Create
michael@0 1010 * nssHash_Destroy
michael@0 1011 * nssHash_Add
michael@0 1012 * nssHash_Remove
michael@0 1013 * nssHash_Count
michael@0 1014 * nssHash_Exists
michael@0 1015 * nssHash_Lookup
michael@0 1016 * nssHash_Iterate
michael@0 1017 */
michael@0 1018
michael@0 1019 /*
michael@0 1020 * nssHash_Create
michael@0 1021 *
michael@0 1022 */
michael@0 1023
michael@0 1024 NSS_EXTERN nssHash *
michael@0 1025 nssHash_Create
michael@0 1026 (
michael@0 1027 NSSArena *arenaOpt,
michael@0 1028 PRUint32 numBuckets,
michael@0 1029 PLHashFunction keyHash,
michael@0 1030 PLHashComparator keyCompare,
michael@0 1031 PLHashComparator valueCompare
michael@0 1032 );
michael@0 1033
michael@0 1034 NSS_EXTERN nssHash *
michael@0 1035 nssHash_CreatePointer
michael@0 1036 (
michael@0 1037 NSSArena *arenaOpt,
michael@0 1038 PRUint32 numBuckets
michael@0 1039 );
michael@0 1040
michael@0 1041 NSS_EXTERN nssHash *
michael@0 1042 nssHash_CreateString
michael@0 1043 (
michael@0 1044 NSSArena *arenaOpt,
michael@0 1045 PRUint32 numBuckets
michael@0 1046 );
michael@0 1047
michael@0 1048 NSS_EXTERN nssHash *
michael@0 1049 nssHash_CreateItem
michael@0 1050 (
michael@0 1051 NSSArena *arenaOpt,
michael@0 1052 PRUint32 numBuckets
michael@0 1053 );
michael@0 1054
michael@0 1055 /*
michael@0 1056 * nssHash_Destroy
michael@0 1057 *
michael@0 1058 */
michael@0 1059 NSS_EXTERN void
michael@0 1060 nssHash_Destroy
michael@0 1061 (
michael@0 1062 nssHash *hash
michael@0 1063 );
michael@0 1064
michael@0 1065 /*
michael@0 1066 * nssHash_Add
michael@0 1067 *
michael@0 1068 */
michael@0 1069
michael@0 1070 extern const NSSError NSS_ERROR_HASH_COLLISION;
michael@0 1071
michael@0 1072 NSS_EXTERN PRStatus
michael@0 1073 nssHash_Add
michael@0 1074 (
michael@0 1075 nssHash *hash,
michael@0 1076 const void *key,
michael@0 1077 const void *value
michael@0 1078 );
michael@0 1079
michael@0 1080 /*
michael@0 1081 * nssHash_Remove
michael@0 1082 *
michael@0 1083 */
michael@0 1084 NSS_EXTERN void
michael@0 1085 nssHash_Remove
michael@0 1086 (
michael@0 1087 nssHash *hash,
michael@0 1088 const void *it
michael@0 1089 );
michael@0 1090
michael@0 1091 /*
michael@0 1092 * nssHash_Count
michael@0 1093 *
michael@0 1094 */
michael@0 1095 NSS_EXTERN PRUint32
michael@0 1096 nssHash_Count
michael@0 1097 (
michael@0 1098 nssHash *hash
michael@0 1099 );
michael@0 1100
michael@0 1101 /*
michael@0 1102 * nssHash_Exists
michael@0 1103 *
michael@0 1104 */
michael@0 1105 NSS_EXTERN PRBool
michael@0 1106 nssHash_Exists
michael@0 1107 (
michael@0 1108 nssHash *hash,
michael@0 1109 const void *it
michael@0 1110 );
michael@0 1111
michael@0 1112 /*
michael@0 1113 * nssHash_Lookup
michael@0 1114 *
michael@0 1115 */
michael@0 1116 NSS_EXTERN void *
michael@0 1117 nssHash_Lookup
michael@0 1118 (
michael@0 1119 nssHash *hash,
michael@0 1120 const void *it
michael@0 1121 );
michael@0 1122
michael@0 1123 /*
michael@0 1124 * nssHash_Iterate
michael@0 1125 *
michael@0 1126 */
michael@0 1127 NSS_EXTERN void
michael@0 1128 nssHash_Iterate
michael@0 1129 (
michael@0 1130 nssHash *hash,
michael@0 1131 nssHashIterator fcn,
michael@0 1132 void *closure
michael@0 1133 );
michael@0 1134
michael@0 1135
michael@0 1136 /*
michael@0 1137 * nssPointerTracker
michael@0 1138 *
michael@0 1139 * This type and these methods are only present in debug builds.
michael@0 1140 *
michael@0 1141 * The nonpublic methods relating to this type are:
michael@0 1142 *
michael@0 1143 * nssPointerTracker_initialize
michael@0 1144 * nssPointerTracker_finalize
michael@0 1145 * nssPointerTracker_add
michael@0 1146 * nssPointerTracker_remove
michael@0 1147 * nssPointerTracker_verify
michael@0 1148 */
michael@0 1149
michael@0 1150 /*
michael@0 1151 * nssPointerTracker_initialize
michael@0 1152 *
michael@0 1153 * This method is only present in debug builds.
michael@0 1154 *
michael@0 1155 * This routine initializes an nssPointerTracker object. Note that
michael@0 1156 * the object must have been declared *static* to guarantee that it
michael@0 1157 * is in a zeroed state initially. This routine is idempotent, and
michael@0 1158 * may even be safely called by multiple threads simultaneously with
michael@0 1159 * the same argument. This routine returns a PRStatus value; if
michael@0 1160 * successful, it will return PR_SUCCESS. On failure it will set an
michael@0 1161 * error on the error stack and return PR_FAILURE.
michael@0 1162 *
michael@0 1163 * The error may be one of the following values:
michael@0 1164 * NSS_ERROR_NO_MEMORY
michael@0 1165 *
michael@0 1166 * Return value:
michael@0 1167 * PR_SUCCESS
michael@0 1168 * PR_FAILURE
michael@0 1169 */
michael@0 1170
michael@0 1171 #ifdef DEBUG
michael@0 1172 NSS_EXTERN PRStatus
michael@0 1173 nssPointerTracker_initialize
michael@0 1174 (
michael@0 1175 nssPointerTracker *tracker
michael@0 1176 );
michael@0 1177
michael@0 1178 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 1179 #endif /* DEBUG */
michael@0 1180
michael@0 1181 /*
michael@0 1182 * nssPointerTracker_finalize
michael@0 1183 *
michael@0 1184 * This method is only present in debug builds.
michael@0 1185 *
michael@0 1186 * This routine returns the nssPointerTracker object to the pre-
michael@0 1187 * initialized state, releasing all resources used by the object.
michael@0 1188 * It will *NOT* destroy the objects being tracked by the pointer
michael@0 1189 * (should any remain), and therefore cannot be used to "sweep up"
michael@0 1190 * remaining objects. This routine returns a PRStatus value; if
michael@0 1191 * successful, it will return PR_SUCCES. On failure it will set an
michael@0 1192 * error on the error stack and return PR_FAILURE. If any objects
michael@0 1193 * remain in the tracker when it is finalized, that will be treated
michael@0 1194 * as an error.
michael@0 1195 *
michael@0 1196 * The error may be one of the following values:
michael@0 1197 * NSS_ERROR_TRACKER_NOT_EMPTY
michael@0 1198 *
michael@0 1199 * Return value:
michael@0 1200 * PR_SUCCESS
michael@0 1201 * PR_FAILURE
michael@0 1202 */
michael@0 1203
michael@0 1204 #ifdef DEBUG
michael@0 1205 NSS_EXTERN PRStatus
michael@0 1206 nssPointerTracker_finalize
michael@0 1207 (
michael@0 1208 nssPointerTracker *tracker
michael@0 1209 );
michael@0 1210
michael@0 1211 extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY;
michael@0 1212 #endif /* DEBUG */
michael@0 1213
michael@0 1214 /*
michael@0 1215 * nssPointerTracker_add
michael@0 1216 *
michael@0 1217 * This method is only present in debug builds.
michael@0 1218 *
michael@0 1219 * This routine adds the specified pointer to the nssPointerTracker
michael@0 1220 * object. It should be called in constructor objects to register
michael@0 1221 * new valid objects. The nssPointerTracker is threadsafe, but this
michael@0 1222 * call is not idempotent. This routine returns a PRStatus value;
michael@0 1223 * if successful it will return PR_SUCCESS. On failure it will set
michael@0 1224 * an error on the error stack and return PR_FAILURE.
michael@0 1225 *
michael@0 1226 * The error may be one of the following values:
michael@0 1227 * NSS_ERROR_NO_MEMORY
michael@0 1228 * NSS_ERROR_TRACKER_NOT_INITIALIZED
michael@0 1229 * NSS_ERROR_DUPLICATE_POINTER
michael@0 1230 *
michael@0 1231 * Return value:
michael@0 1232 * PR_SUCCESS
michael@0 1233 * PR_FAILURE
michael@0 1234 */
michael@0 1235
michael@0 1236 #ifdef DEBUG
michael@0 1237 NSS_EXTERN PRStatus
michael@0 1238 nssPointerTracker_add
michael@0 1239 (
michael@0 1240 nssPointerTracker *tracker,
michael@0 1241 const void *pointer
michael@0 1242 );
michael@0 1243
michael@0 1244 extern const NSSError NSS_ERROR_NO_MEMORY;
michael@0 1245 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
michael@0 1246 extern const NSSError NSS_ERROR_DUPLICATE_POINTER;
michael@0 1247 #endif /* DEBUG */
michael@0 1248
michael@0 1249 /*
michael@0 1250 * nssPointerTracker_remove
michael@0 1251 *
michael@0 1252 * This method is only present in debug builds.
michael@0 1253 *
michael@0 1254 * This routine removes the specified pointer from the
michael@0 1255 * nssPointerTracker object. It does not call any destructor for the
michael@0 1256 * object; rather, this should be called from the object's destructor.
michael@0 1257 * The nssPointerTracker is threadsafe, but this call is not
michael@0 1258 * idempotent. This routine returns a PRStatus value; if successful
michael@0 1259 * it will return PR_SUCCESS. On failure it will set an error on the
michael@0 1260 * error stack and return PR_FAILURE.
michael@0 1261 *
michael@0 1262 * The error may be one of the following values:
michael@0 1263 * NSS_ERROR_TRACKER_NOT_INITIALIZED
michael@0 1264 * NSS_ERROR_POINTER_NOT_REGISTERED
michael@0 1265 *
michael@0 1266 * Return value:
michael@0 1267 * PR_SUCCESS
michael@0 1268 * PR_FAILURE
michael@0 1269 */
michael@0 1270
michael@0 1271 #ifdef DEBUG
michael@0 1272 NSS_EXTERN PRStatus
michael@0 1273 nssPointerTracker_remove
michael@0 1274 (
michael@0 1275 nssPointerTracker *tracker,
michael@0 1276 const void *pointer
michael@0 1277 );
michael@0 1278
michael@0 1279 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
michael@0 1280 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
michael@0 1281 #endif /* DEBUG */
michael@0 1282
michael@0 1283 /*
michael@0 1284 * nssPointerTracker_verify
michael@0 1285 *
michael@0 1286 * This method is only present in debug builds.
michael@0 1287 *
michael@0 1288 * This routine verifies that the specified pointer has been registered
michael@0 1289 * with the nssPointerTracker object. The nssPointerTracker object is
michael@0 1290 * threadsafe, and this call may be safely called from multiple threads
michael@0 1291 * simultaneously with the same arguments. This routine returns a
michael@0 1292 * PRStatus value; if the pointer is registered this will return
michael@0 1293 * PR_SUCCESS. Otherwise it will set an error on the error stack and
michael@0 1294 * return PR_FAILURE. Although the error is suitable for leaving on
michael@0 1295 * the stack, callers may wish to augment the information available by
michael@0 1296 * placing a more type-specific error on the stack.
michael@0 1297 *
michael@0 1298 * The error may be one of the following values:
michael@0 1299 * NSS_ERROR_POINTER_NOT_REGISTERED
michael@0 1300 *
michael@0 1301 * Return value:
michael@0 1302 * PR_SUCCESS
michael@0 1303 * PR_FAILRUE
michael@0 1304 */
michael@0 1305
michael@0 1306 #ifdef DEBUG
michael@0 1307 NSS_EXTERN PRStatus
michael@0 1308 nssPointerTracker_verify
michael@0 1309 (
michael@0 1310 nssPointerTracker *tracker,
michael@0 1311 const void *pointer
michael@0 1312 );
michael@0 1313
michael@0 1314 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
michael@0 1315 #endif /* DEBUG */
michael@0 1316
michael@0 1317 /*
michael@0 1318 * libc
michael@0 1319 *
michael@0 1320 * nsslibc_memcpy
michael@0 1321 * nsslibc_memset
michael@0 1322 * nsslibc_offsetof
michael@0 1323 */
michael@0 1324
michael@0 1325 /*
michael@0 1326 * nsslibc_memcpy
michael@0 1327 *
michael@0 1328 * Errors:
michael@0 1329 * NSS_ERROR_INVALID_POINTER
michael@0 1330 *
michael@0 1331 * Return value:
michael@0 1332 * NULL on error
michael@0 1333 * The destination pointer on success
michael@0 1334 */
michael@0 1335
michael@0 1336 NSS_EXTERN void *
michael@0 1337 nsslibc_memcpy
michael@0 1338 (
michael@0 1339 void *dest,
michael@0 1340 const void *source,
michael@0 1341 PRUint32 n
michael@0 1342 );
michael@0 1343
michael@0 1344 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 1345
michael@0 1346 /*
michael@0 1347 * nsslibc_memset
michael@0 1348 *
michael@0 1349 * Errors:
michael@0 1350 * NSS_ERROR_INVALID_POINTER
michael@0 1351 *
michael@0 1352 * Return value:
michael@0 1353 * NULL on error
michael@0 1354 * The destination pointer on success
michael@0 1355 */
michael@0 1356
michael@0 1357 NSS_EXTERN void *
michael@0 1358 nsslibc_memset
michael@0 1359 (
michael@0 1360 void *dest,
michael@0 1361 PRUint8 byte,
michael@0 1362 PRUint32 n
michael@0 1363 );
michael@0 1364
michael@0 1365 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 1366
michael@0 1367 /*
michael@0 1368 * nsslibc_memequal
michael@0 1369 *
michael@0 1370 * Errors:
michael@0 1371 * NSS_ERROR_INVALID_POINTER
michael@0 1372 *
michael@0 1373 * Return value:
michael@0 1374 * PR_TRUE if they match
michael@0 1375 * PR_FALSE if they don't
michael@0 1376 * PR_FALSE upon error
michael@0 1377 */
michael@0 1378
michael@0 1379 NSS_EXTERN PRBool
michael@0 1380 nsslibc_memequal
michael@0 1381 (
michael@0 1382 const void *a,
michael@0 1383 const void *b,
michael@0 1384 PRUint32 len,
michael@0 1385 PRStatus *statusOpt
michael@0 1386 );
michael@0 1387
michael@0 1388 extern const NSSError NSS_ERROR_INVALID_POINTER;
michael@0 1389
michael@0 1390 #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb)))
michael@0 1391
michael@0 1392 PR_END_EXTERN_C
michael@0 1393
michael@0 1394 #endif /* BASE_H */

mercurial