@@ -187,7 +187,7 @@ typedef struct UriIp6Struct {
187187} UriIp6 ; /**< @copydoc UriIp6Struct */
188188
189189
190- struct UriMemoryManagerStruct ; /* foward declaration to break loop */
190+ struct UriMemoryManagerStruct ; /* forward declaration to break loop */
191191
192192
193193/**
@@ -287,28 +287,34 @@ typedef enum UriResolutionOptionsEnum {
287287
288288
289289/**
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.
292292 *
293293 * 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.
297298 *
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>
304310 *
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.
308314 *
309315 * @param memory <b>OUT</b>: Where to write the wrapped memory manager to
310316 * @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
312318 *
313319 * @see uriEmulateCalloc
314320 * @see uriEmulateReallocarray
@@ -321,7 +327,7 @@ URI_PUBLIC int uriCompleteMemoryManager(UriMemoryManager * memory,
321327
322328
323329/**
324- * Offers emulation of calloc(3) based on memory-> malloc and memset.
330+ * Offers emulation of calloc(3) based on memory-> malloc and memset.
325331 * See "man 3 calloc" as well.
326332 *
327333 * @param memory <b>IN</b>: Memory manager to use, should not be NULL
@@ -340,11 +346,11 @@ URI_PUBLIC void * uriEmulateCalloc(UriMemoryManager * memory,
340346
341347
342348/**
343- * Offers emulation of reallocarray(3) based on memory-> realloc.
349+ * Offers emulation of reallocarray(3) based on memory-> realloc.
344350 * See "man 3 reallocarray" as well.
345351 *
346352 * @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
348354 * @param nmemb <b>IN</b>: Number of elements to allocate
349355 * @param size <b>IN</b>: Size in bytes per element
350356 * @return Pointer to allocated memory or NULL
@@ -369,18 +375,52 @@ URI_PUBLIC void * uriEmulateReallocarray(UriMemoryManager * memory,
369375 * 5. and frees that memory.
370376 *
371377 * 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.
373383 *
374384 * @param memory <b>IN</b>: Memory manager to use, should not be NULL
375385 * @return Error code or 0 on success
376386 *
377387 * @see uriEmulateCalloc
378388 * @see uriEmulateReallocarray
379389 * @see UriMemoryManager
390+ * @see uriTestMemoryManagerEx
380391 * @since 0.9.0
381392 */
382393URI_PUBLIC int uriTestMemoryManager (UriMemoryManager * memory );
383394
384395
385396
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+
386426#endif /* URI_BASE_H */
0 commit comments