QCBOR
Loading...
Searching...
No Matches
Data Fields
q_useful_buf_c Struct Reference

#include <UsefulBuf.h>

Data Fields

const void * ptr
 
size_t len
 

Detailed Description

UsefulBufC and UsefulBuf are simple data structures to hold a pointer and length for 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 coding practice as the length is 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 an empty 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 mode is to pass a UsefulBuf to a function, the function puts some data in it, then the function returns a UsefulBufC refering to the data. The UsefulBuf is a non-const "in" parameter and the UsefulBufC is a const "out" parameter so the constness stays correct. There is no single "in,out" parameter (if there was, it would have to be non-const). Note that the pointer returned in the UsefulBufC usually ends up being the same pointer passed in as a UsefulBuf, though this is not striclty required.

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

There are functions and macros for the following:

  • Initializing
  • Create initialized const UsefulBufC from compiler literals
  • Create initialized const UsefulBufC from NULL-terminated string
  • Make an empty UsefulBuf on the stack
  • Checking whether a UsefulBuf is null, empty or both
  • Copying, copying with offset, copying head or tail
  • Comparing and finding substrings

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.

Another way to look at it is this. C has the NULL-terminated string as a means for handling text strings, but no means or convention for binary strings. Other languages do have such means, Rust, an efficient compiled language, for example.

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".

The documentation for this struct was generated from the following file:
Generated by doxygen 1.12.0