tralloc

A C library that adds size information to memory allocations.
git clone git://src.gearsix.net/tralloc
Log | Files | Refs | Atom | README

commit 9ac0159d176abb7d0edd016831005206ea274ae6
parent 6673b3b3ca47c805b8a6966bd9ae6e09636a34ca
Author: gearsix <gearsix@tuta.io>
Date:   Fri, 16 Sep 2022 15:46:32 +0100

minor improvements to README.md

Diffstat:
MREADME.md | 53++++++++++++++++++++++++++++++++---------------------
1 file changed, 32 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md @@ -1,50 +1,60 @@ # tralloc - track allocations -An ANSI-C libray for tracking heap-allocated memory. +An C libray for tracking the size of heap-allocated memory blocks. + +This is more of a proof-of-concept than anything and I wouldn't +recommend using it in production. There's an accompanying article +here: +[Tracking Allocations in C](gearsix.net/software/tracking-allocations-in-c/) + ## Overview This library provides several functions that act as wrappers -around the _stdlib_ memory allocation functions to track and -provide information on the number of heap-allocated bytes for -individual pointers and overall. +around the _stdlib_ memory allocation functions to provide +information on the number of heap-allocated bytes for individual +pointers and overall. It's implemented with functions the act as _stdlib_ wrappers so that it can sit ontop of whatever _stdlib_ implementation you're using. The downside of this is that it's unable to track any -allocations made without these wrappers. This is acceptable since -it's intended to be used for tracking allocations made by yourself. +allocations made without these wrappers. -There are also a few usability pitfalls: if you call some of the -functions on pointers that **have not** been allocated by tralloc -allocation functions, then it'll cause a memory error. +There are also a few usability pitfalls: +- If you call some of the functions on pointers that **have not** +been allocated by tralloc allocation functions, then it'll probably +cause a memory error. This behaviour is consistent with stdlib though. Make sure to read function documentation. +- If you use a *tralloc* pointer to an address that wasn't returned +by tralloc (either from incrementing/decrementing it), then it'll +cause a memory error. This was done more as a personal exercise than anything, most of the time in C you'll track allocated memory yourself. This was just a cool idea I got carried away with. + ## Goals - Track the total number of heap-allocated bytes. -- Track number of bytes allocated for individual pointers. -- Don't get in the way of any users. +- Track number of bytes allocated for individual memory blocks. +- Don't get in the way of any users, behave as regular stdlib. + ## Guidelines - **Do not** call `tralloc_realloc()`, `tralloc_allocsiz()` or -`tralloc_free` on a pointer not allocated by one of the tralloc stdlib -wrapper functions (same way you wouldn't call free on a pointer you -didn't allocate with stdlib). Otherwise you'll probably run into a -segfault. -- Don't expect tralloc to track memory allocated outside of it's own -tralloc functions. +`tralloc_free` on an address not returned by one of the tralloc stdlib +wrapper functions. +- Don't expect tralloc to work on a non-tralloc pointer address. - You should be able to use the _tralloc stdlib wrappers_ just as you would use their stdlib counterparts without error. - If you want to use `malloc` instead of `tr_malloc`, use a macro. See `test.c` for an example of this. +- It's experimental, so don't do anything silly and expect it to work. + ## API @@ -52,7 +62,7 @@ See `test.c` for an example of this. size_t tralloc_siz(); -Returns the number of bytes heap-allocated by _tralloc memory allocation_ +Returns the number of bytes heap-allocated by *tralloc memory allocation* functions. **tralloc_limit** @@ -77,7 +87,8 @@ Returns `n` if successful and 0 if unsuccessful. Returns number of bytes allocated for `ptr`. -> `ptr` **must** be a _tralloc allocated pointer_. +> `ptr` **must** be a the address returned by a tralloc allocation. + ### stdlib wrappers @@ -101,13 +112,13 @@ used by functions within the library for tracking the heapsiz. void *tralloc_realloc(void *ptr, size_t n); -> `ptr` **must** be a pointer allocated by tralloc. +> `ptr` **must** be a the address returned by a tralloc allocation. **tralloc_free** void tralloc_free(void *ptr); -> `ptr` **must** be a pointer allocated by tralloc. +> `ptr` **must** be a the address returned by a tralloc allocation. ## Authors