@@ -187,7 +187,7 @@ typedef struct UriIp6Struct {
187
187
} UriIp6 ; /**< @copydoc UriIp6Struct */
188
188
189
189
190
- struct UriMemoryManagerStruct ; /* foward declaration to break loop */
190
+ struct UriMemoryManagerStruct ; /* forward declaration to break loop */
191
191
192
192
193
193
/**
@@ -287,28 +287,34 @@ typedef enum UriResolutionOptionsEnum {
287
287
288
288
289
289
/**
290
- * Wraps a memory manager backend that only provides malloc and free
291
- * to make a complete memory manager ready to be used.
290
+ * Wraps a memory manager backend that only provides <c> malloc(3)</c> and
291
+ * <c>free(3)</c> to make a complete memory manager ready to be used.
292
292
*
293
293
* The core feature of this wrapper is that you don't need to implement
294
- * realloc if you don't want to. The wrapped memory manager uses
295
- * backend->malloc, memcpy, and backend->free and soieof(size_t) extra
296
- * bytes per allocation to emulate fallback realloc for you.
294
+ * <c>realloc(3)</c> if you don't want to. The wrapped memory manager uses
295
+ * <c>backend->malloc</c>, <c>memcpy(3)</c>, and <c>backend->free</c> and
296
+ * (at least) <c>sizeof(size_t)</c> extra bytes per allocation to emulate
297
+ * fallback <c>realloc(3)</c> for you.
297
298
*
298
- * memory->calloc is uriEmulateCalloc.
299
- * memory->free uses backend->free and handles the size header.
300
- * memory->malloc uses backend->malloc and adds a size header.
301
- * memory->realloc uses memory->malloc, memcpy, and memory->free and reads
302
- * the size header.
303
- * memory->reallocarray is uriEmulateReallocarray.
299
+ * <ul>
300
+ * <li><c>memory->calloc</c> is <c>uriEmulateCalloc</c>.</li>
301
+ * <li><c>memory->free</c> uses <c>backend->free</c>,
302
+ * and handles the size header.</li>
303
+ * <li><c>memory->malloc</c> uses <c>backend->malloc</c>,
304
+ * and adds a size header.</li>
305
+ * <li><c>memory->realloc</c> uses <c>memory->malloc</c>,
306
+ * <c>memcpy(3)</c> and <c>memory->free</c>,
307
+ * and reads the size header.</li>
308
+ * <li><c>memory->reallocarray</c> is <c>uriEmulateReallocarray</c>.</li>
309
+ * </ul>
304
310
*
305
- * The internal workings behind memory-> free, memory-> malloc, and
306
- * memory-> realloc may change so the functions exposed by these function
307
- * pointer sshould be consided internal and not public API.
311
+ * The internal workings behind <c> memory-> free</c>, <c> memory-> malloc</c>,
312
+ * and <c> memory-> realloc</c> may change, and the functions exposed by these
313
+ * function pointers should be considered internal and not public API.
308
314
*
309
315
* @param memory <b>OUT</b>: Where to write the wrapped memory manager to
310
316
* @param backend <b>IN</b>: Memory manager to use as a backend
311
- * @return Error code or 0 on success
317
+ * @return Error code or 0 on success
312
318
*
313
319
* @see uriEmulateCalloc
314
320
* @see uriEmulateReallocarray
@@ -321,7 +327,7 @@ URI_PUBLIC int uriCompleteMemoryManager(UriMemoryManager * memory,
321
327
322
328
323
329
/**
324
- * Offers emulation of calloc(3) based on memory-> malloc and memset.
330
+ * Offers emulation of calloc(3) based on memory-> malloc and memset.
325
331
* See "man 3 calloc" as well.
326
332
*
327
333
* @param memory <b>IN</b>: Memory manager to use, should not be NULL
@@ -340,11 +346,11 @@ URI_PUBLIC void * uriEmulateCalloc(UriMemoryManager * memory,
340
346
341
347
342
348
/**
343
- * Offers emulation of reallocarray(3) based on memory-> realloc.
349
+ * Offers emulation of reallocarray(3) based on memory-> realloc.
344
350
* See "man 3 reallocarray" as well.
345
351
*
346
352
* @param memory <b>IN</b>: Memory manager to use, should not be NULL
347
- * @param ptr <b>IN</b>: Pointer allocated using memory-> malloc/... or NULL
353
+ * @param ptr <b>IN</b>: Pointer allocated using memory-> malloc/... or NULL
348
354
* @param nmemb <b>IN</b>: Number of elements to allocate
349
355
* @param size <b>IN</b>: Size in bytes per element
350
356
* @return Pointer to allocated memory or NULL
@@ -369,18 +375,52 @@ URI_PUBLIC void * uriEmulateReallocarray(UriMemoryManager * memory,
369
375
* 5. and frees that memory.
370
376
*
371
377
* It is recommended to compile with AddressSanitizer enabled
372
- * to take full advantage of uriTestMemoryManager.
378
+ * to take full advantage of <c>uriTestMemoryManager</c>.
379
+ *
380
+ * For backwards-compatibility, <c>uriTestMemoryManager</c>
381
+ * does not challenge pointer alignment; please see
382
+ * <c>uriTestMemoryManagerEx</c> for that feature.
373
383
*
374
384
* @param memory <b>IN</b>: Memory manager to use, should not be NULL
375
385
* @return Error code or 0 on success
376
386
*
377
387
* @see uriEmulateCalloc
378
388
* @see uriEmulateReallocarray
379
389
* @see UriMemoryManager
390
+ * @see uriTestMemoryManagerEx
380
391
* @since 0.9.0
381
392
*/
382
393
URI_PUBLIC int uriTestMemoryManager (UriMemoryManager * memory );
383
394
384
395
385
396
397
+ /**
398
+ * Run multiple tests against a given memory manager.
399
+ * For example, one test
400
+ * 1. allocates a small amount of memory,
401
+ * 2. writes some magic bytes to it,
402
+ * 3. reallocates it,
403
+ * 4. checks that previous values are still present,
404
+ * 5. and frees that memory.
405
+ *
406
+ * It is recommended to compile with both AddressSanitizer and
407
+ * UndefinedBehaviorSanitizer enabled to take full advantage of
408
+ * <c>uriTestMemoryManagerEx</c>. Note that environment variable
409
+ * <c>UBSAN_OPTIONS</c> may need adjustment to make UndefinedBehaviorSanitizer
410
+ * fatal (which by default it is not).
411
+ *
412
+ * @param memory <b>IN</b>: Memory manager to use, should not be NULL
413
+ * @param challengeAlignment <b>IN</b>: Whether to challenge pointer alignment
414
+ * @return Error code or 0 on success
415
+ *
416
+ * @see uriEmulateCalloc
417
+ * @see uriEmulateReallocarray
418
+ * @see UriMemoryManager
419
+ * @see uriTestMemoryManager
420
+ * @since 0.9.10
421
+ */
422
+ URI_PUBLIC int uriTestMemoryManagerEx (UriMemoryManager * memory , UriBool challengeAlignment );
423
+
424
+
425
+
386
426
#endif /* URI_BASE_H */
0 commit comments