UsefulBufC and UsefulBuf are simple data structures to hold a pointer and length for a binary data.

In C99 this data structure can be passed on the stack making a lot of code cleaner than carrying around a pointer and length as two parameters.

This is also conducive to secure code practice as the lengths are always carried with the pointer and the convention for handling a pointer and a length is clear.

While it might be possible to write buffer and pointer code more efficiently in some use cases, the thought is that unless there is an extreme need for performance (e.g., you are building a gigabit-per-second IP router), it is probably better to have cleaner code you can be most certain about the security of.

The non-const UsefulBuf is usually used to refer a buffer to be filled in. The length is the size of the buffer.

The const UsefulBufC is usually used to refer to some data that has been filled in. The length is amount of valid data pointed to.

A common use is to pass a UsefulBuf to a function, the function fills it in, the function returns a UsefulBufC. The pointer is the same in both.

A UsefulBuf is NULL, it has no value, when the ptr in it is NULL.

There are utility functions for the following:

• Checking for UsefulBufs that are NULL, empty or both
• Copying, copying with offset, copying head or tail
• Comparing and finding substrings
• Initializating
• Create initialized const UsefulBufC from compiler literals
• Create initialized const UsefulBufC from NULL-terminated string
• Make an empty UsefulBuf on the stack

See also UsefulOutBuf. It is a richer structure that has both the size of the valid data and the size of the buffer.

UsefulBuf is only 16 or 8 bytes on a 64- or 32-bit machine so it can go on the stack and be a function parameter or return value.

UsefulBuf is kind of like the Useful Pot Pooh gave Eeyore on his birthday. Eeyore's balloon fits beautifully, "it goes in and out like anything".

Definition at line 149 of file UsefulBuf.h.