The goal of this code is to make buffer and pointer manipulation easier and safer when working with binary data. More...

#include <stdint.h>
#include <string.h>
#include <stddef.h>

Data Structures
struct	useful_buf_c
	UsefulBufC and UsefulBuf are simple data structures to hold a pointer and length for a binary data. More...

struct	useful_buf
	The non-const UsefulBuf typically used for some allocated memory that is to be filled in. More...

struct	useful_out_buf
	UsefulOutBuf is a structure and functions (an object) that are good for serializing data into a buffer such as is often done with network protocols or data written to files. More...

struct	useful_input_buf

Macros
#define	NULLUsefulBufC ((UsefulBufC) {NULL, 0})
	A "NULL" UsefulBufC is one that has no value in the same way a NULL pointer has no value. More...

#define	NULLUsefulBuf ((UsefulBuf) {NULL, 0})
	A NULL UsefulBuf is one that has no memory associated the say way NULL points to nothing. More...

#define	UsefulBuf_FROM_SZ_LITERAL(szString) ((UsefulBufC) {(szString), sizeof(szString)-1})
	Convert a literal string to a UsefulBufC. More...

#define	UsefulBuf_FROM_BYTE_ARRAY_LITERAL(pBytes) ((UsefulBufC) {(pBytes), sizeof(pBytes)})
	Convert a literal byte array to a UsefulBufC. More...

#define	UsefulBuf_MAKE_STACK_UB(name, size)
	Make an automatic variable with name of type UsefulBuf and point it to a stack variable of the give size. More...

#define	UsefulBuf_FROM_BYTE_ARRAY(pBytes) ((UsefulBuf) {(pBytes), sizeof(pBytes)})
	Make a byte array in to a UsefulBuf. More...

#define	UsefulOutBuf_MakeOnStack(name, size)
	Convenience marco to make a UsefulOutBuf on the stack and initialize it with stack buffer. More...

#define	UIB_MAGIC (0xB00F)
	UsefulInputBuf is the counterpart to UsefulOutBuf and is for parsing data read or received. More...

Typedefs
typedef struct useful_buf_c	UsefulBufC
	UsefulBufC and UsefulBuf are simple data structures to hold a pointer and length for a binary data. More...

typedef struct useful_buf	UsefulBuf
	The non-const UsefulBuf typically used for some allocated memory that is to be filled in. More...

typedef struct useful_out_buf	UsefulOutBuf
	UsefulOutBuf is a structure and functions (an object) that are good for serializing data into a buffer such as is often done with network protocols or data written to files. More...

Functions
static int	UsefulBuf_IsNULL (UsefulBuf UB)
	Check if a UsefulBuf is NULL or not. More...

static int	UsefulBuf_IsNULLC (UsefulBufC UB)
	Check if a UsefulBufC is NULL or not. More...

static int	UsefulBuf_IsEmpty (UsefulBuf UB)
	Check if a UsefulBuf is empty or not. More...

static int	UsefulBuf_IsEmptyC (UsefulBufC UB)
	Check if a UsefulBufC is empty or not. More...

static int	UsefulBuf_IsNULLOrEmpty (UsefulBuf UB)
	Check if a UsefulBuf is NULL or empty. More...

static int	UsefulBuf_IsNULLOrEmptyC (UsefulBufC UB)
	Check if a UsefulBufC is NULL or empty. More...

static UsefulBufC	UsefulBuf_Const (const UsefulBuf UB)
	Convert a non const UsefulBuf to a const UsefulBufC. More...

static UsefulBuf	UsefulBuf_Unconst (const UsefulBufC UBC)
	Convert a const UsefulBufC to a non-const UsefulBuf. More...

static UsefulBufC	UsefulBuf_FromSZ (const char *szString)
	Convert a NULL terminated string to a UsefulBufC. More...

UsefulBufC	UsefulBuf_CopyOffset (UsefulBuf Dest, size_t uOffset, const UsefulBufC Src)
	Copy one UsefulBuf into another at an offset. More...

static UsefulBufC	UsefulBuf_Copy (UsefulBuf Dest, const UsefulBufC Src)
	Copy one UsefulBuf into another. More...

static UsefulBufC	UsefulBuf_Set (UsefulBuf pDest, uint8_t value)
	Set all bytes in a UsefulBuf to a value, for example 0. More...

static UsefulBufC	UsefulBuf_CopyPtr (UsefulBuf Dest, const void *ptr, size_t len)
	Copy a pointer into a UsefulBuf. More...

static UsefulBufC	UsefulBuf_Head (UsefulBufC UB, size_t uAmount)
	Returns a truncation of a UsefulBufC. More...

static UsefulBufC	UsefulBuf_Tail (UsefulBufC UB, size_t uAmount)
	Returns bytes from the end of a UsefulBufC. More...

int	UsefulBuf_Compare (const UsefulBufC UB1, const UsefulBufC UB2)
	Compare two UsefulBufCs. More...

size_t	UsefulBuf_FindBytes (UsefulBufC BytesToSearch, UsefulBufC BytesToFind)
	Find one UsefulBuf in another. More...

void	UsefulOutBuf_Init (UsefulOutBuf *me, UsefulBuf Storage)
	Initialize and supply the actual output buffer. More...

static void	UsefulOutBuf_Reset (UsefulOutBuf *me)
	Reset a UsefulOutBuf for re use. More...

static size_t	UsefulOutBuf_GetEndPosition (UsefulOutBuf *me)
	Returns position of end of data in the UsefulOutBuf. More...

static int	UsefulOutBuf_AtStart (UsefulOutBuf *me)
	Returns whether any data has been added to the UsefulOutBuf. More...

void	UsefulOutBuf_InsertUsefulBuf (UsefulOutBuf *me, UsefulBufC NewData, size_t uPos)
	Inserts bytes into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertData (UsefulOutBuf me, const void pBytes, size_t uLen, size_t uPos)
	Insert a data buffer into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertString (UsefulOutBuf me, const char szString, size_t uPos)
	Insert a NULL-terminated string into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertByte (UsefulOutBuf *me, uint8_t byte, size_t uPos)
	Insert a byte into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertUint16 (UsefulOutBuf *me, uint16_t uInteger16, size_t uPos)
	Insert a 16-bit integer into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertUint32 (UsefulOutBuf *me, uint32_t uInteger32, size_t uPos)
	Insert a 32-bit integer into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertUint64 (UsefulOutBuf *me, uint64_t uInteger64, size_t uPos)
	Insert a 64-bit integer into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertFloat (UsefulOutBuf *me, float f, size_t uPos)
	Insert a float into the UsefulOutBuf. More...

static void	UsefulOutBuf_InsertDouble (UsefulOutBuf *me, double d, size_t uPos)
	Insert a double into the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendUsefulBuf (UsefulOutBuf *me, UsefulBufC NewData)
	Append a UsefulBuf into the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendData (UsefulOutBuf me, const void pBytes, size_t uLen)
	Append bytes to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendString (UsefulOutBuf me, const char szString)
	Append a NULL-terminated string to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendByte (UsefulOutBuf *me, uint8_t byte)
	Append a byte to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendUint16 (UsefulOutBuf *me, uint16_t uInteger16)
	Append an integer to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendUint32 (UsefulOutBuf *me, uint32_t uInteger32)
	Append an integer to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendUint64 (UsefulOutBuf *me, uint64_t uInteger64)
	Append an integer to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendFloat (UsefulOutBuf *me, float f)
	Append a float to the UsefulOutBuf. More...

static void	UsefulOutBuf_AppendDouble (UsefulOutBuf *me, double d)
	Append a float to the UsefulOutBuf. More...

static int	UsefulOutBuf_GetError (UsefulOutBuf *me)
	Returns the current error status. More...

static size_t	UsefulOutBuf_RoomLeft (UsefulOutBuf *me)
	Returns number of bytes unused used in the output buffer. More...

static int	UsefulOutBuf_WillItFit (UsefulOutBuf *me, size_t uLen)
	Returns true / false if some number of bytes will fit in the UsefulOutBuf. More...

UsefulBufC	UsefulOutBuf_OutUBuf (UsefulOutBuf *me)
	Returns the resulting valid data in a UsefulOutBuf. More...

UsefulBufC	UsefulOutBuf_CopyOut (UsefulOutBuf *me, UsefulBuf Dest)
	Copies the valid data out into a supplied buffer. More...

static void	UsefulInputBuf_Init (UsefulInputBuf *me, UsefulBufC UB)
	Initialize the UsefulInputBuf structure before use. More...

static size_t	UsefulInputBuf_Tell (UsefulInputBuf *me)
	Returns current position in input buffer. More...

static void	UsefulInputBuf_Seek (UsefulInputBuf *me, size_t uPos)
	Sets current position in input buffer. More...

static size_t	UsefulInputBuf_BytesUnconsumed (UsefulInputBuf *me)
	Returns the number of bytes from the cursor to the end of the buffer, the uncomsummed bytes. More...

static int	UsefulInputBuf_BytesAvailable (UsefulInputBuf *me, size_t uLen)
	Check if there are any unconsumed bytes. More...

const void *	UsefulInputBuf_GetBytes (UsefulInputBuf *me, size_t uNum)
	Get pointer to bytes out of the input buffer. More...

static UsefulBufC	UsefulInputBuf_GetUsefulBuf (UsefulInputBuf *me, size_t uNum)
	Get UsefulBuf out of the input buffer. More...

static uint8_t	UsefulInputBuf_GetByte (UsefulInputBuf *me)
	Get a byte out of the input buffer. More...

static uint16_t	UsefulInputBuf_GetUint16 (UsefulInputBuf *me)
	Get a uint16_t out of the input buffer. More...

static uint32_t	UsefulInputBuf_GetUint32 (UsefulInputBuf *me)
	Get a uint32_t out of the input buffer. More...

static uint64_t	UsefulInputBuf_GetUint64 (UsefulInputBuf *me)
	Get a uint64_t out of the input buffer. More...

static float	UsefulInputBuf_GetFloat (UsefulInputBuf *me)
	Get a float out of the input buffer. More...

static double	UsefulInputBuf_GetDouble (UsefulInputBuf *me)
	Get a double out of the input buffer. More...

static int	UsefulInputBuf_GetError (UsefulInputBuf *me)
	Get the error status. More...

Detailed Description

The goal of this code is to make buffer and pointer manipulation easier and safer when working with binary data.

You use the UsefulBuf, UsefulOutBuf and UsefulInputBuf structures to represent buffers rather than ad hoc pointers and lengths.

With these it will often be possible to write code that does little or no direct pointer manipulation for copying and formatting data. For example the QCBOR encoder was rewritten using these and has no direct pointer manipulation.

While it is true that object code using these functions will be a little larger and slower than a white-knuckle clever use of pointers might be, but not by that much or enough to have an affect for most use cases. For security-oriented code this is highly worthwhile. Clarity, simplicity, reviewability and are more important.

There are some extra sanity and double checks in this code to help catch coding errors and simple memory corruption. They are helpful, but not a substitute for proper code review, input validation and such.

This code consists of a lot of inline functions and a few that are not. It should not generate very much object code, especially with the optimizer turned up to -Os or -O3. The idea is that the inline functions are easier to review and understand and the optimizer does the work of making the code small.

Definition in file UsefulBuf.h.

Macro Definition Documentation

#define NULLUsefulBuf ((UsefulBuf) {NULL, 0})

A NULL UsefulBuf is one that has no memory associated the say way NULL points to nothing.

It does not matter what len is.

Definition at line 176 of file UsefulBuf.h.

#define NULLUsefulBufC ((UsefulBufC) {NULL, 0})

A "NULL" UsefulBufC is one that has no value in the same way a NULL pointer has no value.

A UsefulBuf is NULL when the ptr field is NULL. It doesn't matter what len is. See UsefulBuf_IsEmpty() for the distinction between NULL and empty.

Definition at line 171 of file UsefulBuf.h.

#define UIB_MAGIC (0xB00F)

UsefulInputBuf is the counterpart to UsefulOutBuf and is for parsing data read or received.

Initialize it with the data from the network and its length. Then use the functions here to get the various data types out of it. It maintains a position for getting the next item. This means you don't have to track a pointer as you get each object. UsefulInputBuf does that for you and makes sure it never goes off the end of the buffer. The QCBOR implementation parser makes use of this for all its pointer math and length checking.

UsefulInputBuf also maintains an internal error state so you do not have to. Once data has been requested off the end of the buffer, it goes into an error state. You can keep calling functions to get more data but they will either return 0 or NULL. As long as you don't dereference the NULL, you can wait until all data items have been fetched before checking for the error and this can simplify your code.

The integer and float parsing expects network byte order (big endian). Network byte order is what is used by TCP/IP, CBOR and most internet protocols.

Lots of inlining is used to keep code size down. The code optimizer, particularly with the -Os, also reduces code size a lot. The only non-inline code is UsefulInputBuf_GetBytes() which is less than 100 bytes so use of UsefulInputBuf doesn't add much code for all the messy hard-to-get right issues with parsing in C that is solves.

The parse context size is: 64-bit machine: 16 + 8 + 2 + 1 (5 bytes padding to align) = 32 bytes 32-bit machine: 8 + 4 + 2 + 1 (1 byte padding to align) = 16 bytes

Definition at line 1200 of file UsefulBuf.h.

#define UsefulBuf_FROM_BYTE_ARRAY ( pBytes ) ((UsefulBuf) {(pBytes), sizeof(pBytes)})

Make a byte array in to a UsefulBuf.

Definition at line 326 of file UsefulBuf.h.

#define UsefulBuf_FROM_BYTE_ARRAY_LITERAL ( pBytes ) ((UsefulBufC) {(pBytes), sizeof(pBytes)})

Convert a literal byte array to a UsefulBufC.

pBytes must be a literal string that you can take sizeof. It will not work on non-literal arrays.

Definition at line 310 of file UsefulBuf.h.

#define UsefulBuf_FROM_SZ_LITERAL ( szString ) ((UsefulBufC) {(szString), sizeof(szString)-1})

Convert a literal string to a UsefulBufC.

szString must be a literal string that you can take sizeof. This is better for literal strings than UsefulBuf_FromSZ() because it generates less code. It will not work on non-literal strings.

The terminating \0 (NULL) is NOT included in the length!

Definition at line 299 of file UsefulBuf.h.

#define UsefulBuf_MAKE_STACK_UB	(	name,
		size
	)

Value:

uint8_t __pBuf##name[(size)];\

UsefulBuf name = {__pBuf##name , sizeof( __pBuf##name )}

Make an automatic variable with name of type UsefulBuf and point it to a stack variable of the give size.

Definition at line 318 of file UsefulBuf.h.

#define UsefulOutBuf_MakeOnStack	(	name,
		size
	)

Value:

uint8_t       __pBuf##name[(size)];\
   UsefulOutBuf  name;\
   UsefulOutBuf_Init(&(name), (UsefulBuf){__pBuf##name, (size)});

Convenience marco to make a UsefulOutBuf on the stack and initialize it with stack buffer.

Definition at line 669 of file UsefulBuf.h.

Typedef Documentation

typedef struct useful_buf UsefulBuf

The non-const UsefulBuf typically used for some allocated memory that is to be filled in.

The len is the amount of memory, not the length of the valid data in the buffer.

typedef struct useful_buf_c UsefulBufC

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

typedef struct useful_out_buf UsefulOutBuf

UsefulOutBuf is a structure and functions (an object) that are good for serializing data into a buffer such as is often done with network protocols or data written to files.

The main idea is that all the pointer manipulation for adding data is done by UsefulOutBuf functions so the caller doesn't have to do any. All the pointer manipulation is centralized here. This code will have been reviewed and written carefully so it spares the caller of much of this work and results in much safer code with much less work.

The functions to add data to the output buffer always check the length and will never write off the end of the output buffer. If an attempt to add data that will not fit is made, an internal error flag will be set and further attempts to add data will not do anything.

Basically, if you initialized with the correct buffer, there is no way to ever write off the end of that buffer when calling the Add and Insert functions here.

The functions to add data do not return an error. The working model is that the caller just makes all the calls to add data without any error checking on each one. The error is instead checked after all the data is added when the result is to be used. This makes the caller's code cleaner.

There is a utility function to get the error status anytime along the way if the caller wants. There are functions to see how much room is left and see if some data will fit too, but their use is generally not necessary.

The general call flow is like this:

Initialize the UsefulOutBuf with the buffer that is to have the data added. The caller allocates the buffer. It can be heap or stack or shared memory (or other).
Make calls to add data to the output buffer. Insert and append are both supported. The append and insert calls will never write off the end of the buffer.
When all data is added, check the error status to make sure everything fit.
Get the resulting serialized data either as a UsefulBuf (a pointer and length) or have it copied to another buffer.

UsefulOutBuf can be initialized with just a buffer length by passing NULL as the pointer to the output buffer. This is useful if you want to go through the whole serialization process to either see if it will fit into a given buffer or compute the size of the buffer needed. Pass a very large buffer size when calling Init, if you want just to compute the size.

Some inexpensive simple sanity checks are performed before every data addition to guard against use of an uninitialized or corrupted UsefulOutBuf.

This has been used to create a CBOR encoder. The CBOR encoder has almost no pointer manipulation in it, is much easier to read, and easier to review.

A UsefulOutBuf is 27 bytes or 15 bytes on 64- or 32-bit machines so it can go on the stack or be a C99 function parameter.

Function Documentation

int UsefulBuf_Compare	(	const UsefulBufC	UB1,
		const UsefulBufC	UB2
	)

Compare two UsefulBufCs.

Parameters

[in]	UB1	The destination buffer to copy into
[in]	UB2	The source to copy from

Returns: 0 if equal...

Returns a negative value if UB1 if is less than UB2. UB1 is less than UB2 if it is shorter or the first byte that is not the same is less.

Returns 0 if the UsefulBufs are the same.

Returns a positive value if UB2 is less than UB1.

All that is of significance is that the result is positive, negative or 0. (This doesn't return the difference between the first non-matching byte like memcmp).

static UsefulBufC UsefulBuf_Const ( const UsefulBuf UB )

static

Convert a non const UsefulBuf to a const UsefulBufC.

Parameters

[in] UB The UsefulBuf to convert

Returns: a UsefulBufC struct

Definition at line 269 of file UsefulBuf.h.

static UsefulBufC UsefulBuf_Copy	(	UsefulBuf	Dest,
		const UsefulBufC	Src
	)

static

Copy one UsefulBuf into another.

Parameters

[in]	Dest	The destination buffer to copy into
[out]	Src	The source to copy from

Returns: filled in UsefulBufC on success, NULLUsefulBufC on failure

This fails if Src.len is greater than Dest.len.

Note that like memcpy, the pointers are not checked and this will crash, rather than return NULLUsefulBufC if they are NULL or invalid.

Results are undefined if Dest and Src overlap.

Definition at line 386 of file UsefulBuf.h.

UsefulBufC UsefulBuf_CopyOffset	(	UsefulBuf	Dest,
		size_t	uOffset,
		const UsefulBufC	Src
	)

Copy one UsefulBuf into another at an offset.

Parameters

[in]	Dest	Destiation buffer to copy into
[in]	uOffset	The byte offset in Dest at which to copy to
[in]	Src	The bytes to copy

Returns: Pointer and length of the copy

This fails and returns NULLUsefulBufC Src.len + uOffset > Dest.len.

Like memcpy, there is no check for NULL. If NULL is passed this will crash.

There is an assumption that there is valid data in Dest up to uOffset as the resulting UsefulBufC returned starts at the beginning of Dest and goes to Src.len + uOffset.

static UsefulBufC UsefulBuf_CopyPtr	(	UsefulBuf	Dest,
		const void *	ptr,
		size_t	len
	)

static

Copy a pointer into a UsefulBuf.

Parameters

[in,out]	Dest	The destination buffer to copy into
[in]	ptr	The source to copy from
[in]	len	Length of the source; amoutn to copy

Returns: 0 on success, 1 on failure

This fails and returns NULLUsefulBufC if len is greater than pDest->len.

Note that like memcpy, the pointers are not checked and this will crash, rather than return 1 if they are NULL or invalid.

Definition at line 425 of file UsefulBuf.h.

size_t UsefulBuf_FindBytes	(	UsefulBufC	BytesToSearch,
		UsefulBufC	BytesToFind
	)

Find one UsefulBuf in another.

Parameters

[in]	BytesToSearch	UsefulBuf to search through
[in]	BytesToFind	UsefulBuf with bytes to be found

Returns: position of found bytes or SIZE_MAX if not found.

static UsefulBufC UsefulBuf_FromSZ ( const char * szString )

static

Convert a NULL terminated string to a UsefulBufC.

Parameters

[in] szString The string to convert

Returns: a UsefulBufC struct

UsefulBufC.ptr points to the string so it's lifetime must be maintained.

The terminating \0 (NULL) is NOT included in the length!

Definition at line 342 of file UsefulBuf.h.

static UsefulBufC UsefulBuf_Head	(	UsefulBufC	UB,
		size_t	uAmount
	)

static

Returns a truncation of a UsefulBufC.

Parameters

[in]	UB	The buffer to get the head of
[in]	uAmount	The number of bytes in the head

Returns: A UsefulBufC that is the head of UB

Definition at line 440 of file UsefulBuf.h.

static int UsefulBuf_IsEmpty ( UsefulBuf UB )

static

Check if a UsefulBuf is empty or not.

Parameters

[in] UB The UsefulBuf to check

Returns: 1 if it is empty, 0 if not.

An "Empty" UsefulBuf is one that has a value and can be considered to be set, but that value is of zero length. It is empty when len is zero. It doesn't matter what the ptr is.

A lot of uses will not need to clearly distinguish a NULL UsefulBuf from an empty one and can have the ptr NULL and the len 0. However if a use of UsefulBuf needs to make a distinction then ptr should not be NULL when the UsefulBuf is considered empty, but not NULL.

Definition at line 220 of file UsefulBuf.h.

static int UsefulBuf_IsEmptyC ( UsefulBufC UB )

static

Check if a UsefulBufC is empty or not.

Parameters

[in] UB The UsefulBufC to check

Returns: 1 if it is empty, 0 if not.

Definition at line 232 of file UsefulBuf.h.

static int UsefulBuf_IsNULL ( UsefulBuf UB )

static

Check if a UsefulBuf is NULL or not.

Parameters

[in] UB The UsefulBuf to check

Returns: 1 if it is NULL, 0 if not.

Definition at line 186 of file UsefulBuf.h.

static int UsefulBuf_IsNULLC ( UsefulBufC UB )

static

Check if a UsefulBufC is NULL or not.

Parameters

[in] UB The UsefulBufC to check

Returns: 1 if it is NULL, 0 if not.

Definition at line 198 of file UsefulBuf.h.

static int UsefulBuf_IsNULLOrEmpty ( UsefulBuf UB )

static

Check if a UsefulBuf is NULL or empty.

Parameters

[in] UB The UsefulBuf to check

Returns: 1 if it is either NULL or empty, 0 if not.

Definition at line 244 of file UsefulBuf.h.

static int UsefulBuf_IsNULLOrEmptyC ( UsefulBufC UB )

static

Check if a UsefulBufC is NULL or empty.

Parameters

[in] UB The UsefulBufC to check

Returns: 1 if it is either NULL or empty, 0 if not.

Definition at line 256 of file UsefulBuf.h.

static UsefulBufC UsefulBuf_Set	(	UsefulBuf	pDest,
		uint8_t	value
	)

static

Set all bytes in a UsefulBuf to a value, for example 0.

Parameters

[in]	pDest	The destination buffer to copy into
[in]	value	The value to set the bytes to

Note that like memset, the pointer in pDest is not checked and this will crash if NULL or invalid.

Definition at line 401 of file UsefulBuf.h.

static UsefulBufC UsefulBuf_Tail	(	UsefulBufC	UB,
		size_t	uAmount
	)

static

Returns bytes from the end of a UsefulBufC.

Parameters

[in]	UB	The buffer to get the tail of
[in]	uAmount	The offset from the start where the tail is to begin

Returns: A UsefulBufC that is the tail of UB or NULLUsefulBufC if uAmount is greater than the length of the UsefulBufC

If the input UsefulBufC is NULL, but the len is not, then the length of the tail will be calculated and returned along with a NULL ptr.

Definition at line 462 of file UsefulBuf.h.

static UsefulBuf UsefulBuf_Unconst ( const UsefulBufC UBC )

static

Convert a const UsefulBufC to a non-const UsefulBuf.

Parameters

[in] UBC The UsefulBuf to convert

Returns: a non const UsefulBuf struct

Definition at line 282 of file UsefulBuf.h.

static int UsefulInputBuf_BytesAvailable	(	UsefulInputBuf *	me,
		size_t	uLen
	)

static

Check if there are any unconsumed bytes.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: 1 if len bytes are available after the cursor, and 0 if not

Definition at line 1312 of file UsefulBuf.h.

static size_t UsefulInputBuf_BytesUnconsumed ( UsefulInputBuf * me )

static

Returns the number of bytes from the cursor to the end of the buffer, the uncomsummed bytes.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: number of bytes unconsumed or 0 on error.

This is a critical function for input length validation. This does some pointer / offset math.

Returns 0 if the cursor it invalid or corruption of the structure is detected.

Code Reviewers: THIS FUNCTION DOES POINTER MATH

Definition at line 1283 of file UsefulBuf.h.

static uint8_t UsefulInputBuf_GetByte ( UsefulInputBuf * me )

static

Get a byte out of the input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The byte

This consumes 1 byte from the input buffer. It returns the byte.

If there is not 1 byte in the buffer, 0 will be returned for the byte and an error set internally. You must check the error at some point to know whether the 0 was the real value or just returned in error, but you may not have to do that right away. Check the error state with UsefulInputBuf_GetError(). You can also know you are in the error state if UsefulInputBuf_GetBytes() returns NULL or the ptr from UsefulInputBuf_GetUsefulBuf() is NULL.

It advances the current position by 1 byte.

Definition at line 1383 of file UsefulBuf.h.

const void* UsefulInputBuf_GetBytes	(	UsefulInputBuf *	me,
		size_t	uNum
	)

Get pointer to bytes out of the input buffer.

Parameters

[in]	me	Pointer to the UsefulInputBuf.
[in]	uNum	Number of bytes to get

Returns: Pointer to bytes.

This consumes n bytes from the input buffer. It returns a pointer to the start of the n bytes.

If there are not n bytes in the input buffer, NULL will be returned and an error will be set.

It advances the current position by n bytes.

static double UsefulInputBuf_GetDouble ( UsefulInputBuf * me )

static

Get a double out of the input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The double

See UsefulInputBuf_GetByte(). This works the same, except it returns a double and eight bytes are consumed.

The input bytes must be in network order (big endian).

Definition at line 1504 of file UsefulBuf.h.

static int UsefulInputBuf_GetError ( UsefulInputBuf * me )

static

Get the error status.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The error.

Zero is success, non-zero is error. Once in the error state, the only way to clear it is to call Init again.

You may be able to only check the error state at the end after all the Get()'s have been done, but if what you get later depends on what you get sooner you cannot. For example if you get a length or count of following items you will have to check the error.

Definition at line 1528 of file UsefulBuf.h.

static float UsefulInputBuf_GetFloat ( UsefulInputBuf * me )

static

Get a float out of the input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The float

See UsefulInputBuf_GetByte(). This works the same, except it returns a float and four bytes are consumed.

The input bytes must be in network order (big endian).

Definition at line 1485 of file UsefulBuf.h.

static uint16_t UsefulInputBuf_GetUint16 ( UsefulInputBuf * me )

static

Get a uint16_t out of the input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The uint16_t

See UsefulInputBuf_GetByte(). This works the same, except it returns a uint16_t and two bytes are consumed.

The input bytes must be in network order (big endian).

Definition at line 1403 of file UsefulBuf.h.

static uint32_t UsefulInputBuf_GetUint32 ( UsefulInputBuf * me )

static

Get a uint32_t out of the input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The uint32_t

See UsefulInputBuf_GetByte(). This works the same, except it returns a uint32_t and four bytes are consumed.

The input bytes must be in network order (big endian).

Definition at line 1427 of file UsefulBuf.h.

static uint64_t UsefulInputBuf_GetUint64 ( UsefulInputBuf * me )

static

Get a uint64_t out of the input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: The uint64_t

See UsefulInputBuf_GetByte(). This works the same, except it returns a uint64_t and eight bytes are consumed.

The input bytes must be in network order (big endian).

Definition at line 1454 of file UsefulBuf.h.

static UsefulBufC UsefulInputBuf_GetUsefulBuf	(	UsefulInputBuf *	me,
		size_t	uNum
	)

static

Get UsefulBuf out of the input buffer.

Parameters

[in]	me	Pointer to the UsefulInputBuf.
[in]	uNum	Number of bytes to get

Returns: UsefulBufC with ptr and length for bytes consumed.

This consumes n bytes from the input buffer and returns the pointer and len to them as a UsefulBufC. The len returned will always be n.

If there are not n bytes in the input buffer, UsefulBufC.ptr will be NULL and UsefulBufC.len will be 0. An error will be set.

It advances the current position by n bytes.

Definition at line 1353 of file UsefulBuf.h.

static void UsefulInputBuf_Init	(	UsefulInputBuf *	me,
		UsefulBufC	UB
	)

static

Initialize the UsefulInputBuf structure before use.

Parameters

[in]	me	Pointer to the UsefulInputBuf instance.
[in]	UB	Pointer to the data to parse.

Definition at line 1219 of file UsefulBuf.h.

static void UsefulInputBuf_Seek	(	UsefulInputBuf *	me,
		size_t	uPos
	)

static

Sets current position in input buffer.

Parameters

[in]	me	Pointer to the UsefulInputBuf.
[in]	uPos	Position to set to

If the position is off the end of the input buffer, the error state is entered and all functions will do nothing.

Seeking to a valid position in the buffer will not reset the error state. Only re initialization will do that.

Definition at line 1257 of file UsefulBuf.h.

static size_t UsefulInputBuf_Tell ( UsefulInputBuf * me )

static

Returns current position in input buffer.

Parameters

[in] me Pointer to the UsefulInputBuf.

Returns: Integer position of the cursor

The position that the next bytes will be returned from.

Definition at line 1238 of file UsefulBuf.h.

static void UsefulOutBuf_AppendByte	(	UsefulOutBuf *	me,
		uint8_t	byte
	)

static

Append a byte to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	byte	Bytes to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

Definition at line 982 of file UsefulBuf.h.

static void UsefulOutBuf_AppendData	(	UsefulOutBuf *	me,
		const void *	pBytes,
		size_t	uLen
	)

static

Append bytes to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	pBytes	Pointer to bytes to append
[in]	uLen	Index in output buffer at which to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

Definition at line 953 of file UsefulBuf.h.

static void UsefulOutBuf_AppendDouble	(	UsefulOutBuf *	me,
		double	d
	)

static

Append a float to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	d	Double to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

The double will be appended in network byte order (big endian).

Definition at line 1059 of file UsefulBuf.h.

static void UsefulOutBuf_AppendFloat	(	UsefulOutBuf *	me,
		float	f
	)

static

Append a float to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	f	Float to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

The float will be appended in network byte order (big endian).

Definition at line 1044 of file UsefulBuf.h.

static void UsefulOutBuf_AppendString	(	UsefulOutBuf *	me,
		const char *	szString
	)

static

Append a NULL-terminated string to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	szString	string to append

Definition at line 967 of file UsefulBuf.h.

static void UsefulOutBuf_AppendUint16	(	UsefulOutBuf *	me,
		uint16_t	uInteger16
	)

static

Append an integer to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	uInteger16	Integer to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

The integer will be appended in network byte order (big endian).

Definition at line 998 of file UsefulBuf.h.

static void UsefulOutBuf_AppendUint32	(	UsefulOutBuf *	me,
		uint32_t	uInteger32
	)

static

Append an integer to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	uInteger32	Integer to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

The integer will be appended in network byte order (big endian).

Definition at line 1013 of file UsefulBuf.h.

static void UsefulOutBuf_AppendUint64	(	UsefulOutBuf *	me,
		uint64_t	uInteger64
	)

static

Append an integer to the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	uInteger64	Integer to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

The integer will be appended in network byte order (big endian).

Definition at line 1028 of file UsefulBuf.h.

static void UsefulOutBuf_AppendUsefulBuf	(	UsefulOutBuf *	me,
		UsefulBufC	NewData
	)

static

Append a UsefulBuf into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	NewData	UsefulBuf with the bytes to append

See UsefulOutBuf_InsertUsefulBuf() for details. This does the same with the insertion point at the end of the valid data.

Definition at line 935 of file UsefulBuf.h.

static int UsefulOutBuf_AtStart ( UsefulOutBuf * me )

static

Returns whether any data has been added to the UsefulOutBuf.

Parameters

[in] me Pointer to the UsefulOutBuf

Returns: 1 if output position is at start

Definition at line 725 of file UsefulBuf.h.

UsefulBufC UsefulOutBuf_CopyOut	(	UsefulOutBuf *	me,
		UsefulBuf	Dest
	)

Copies the valid data out into a supplied buffer.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[out]	Dest	The destination buffer to copy into

Returns: Pointer and length of copied data.

This is the same as UsefulOutBuf_OutUBuf() except it copies the data.

static size_t UsefulOutBuf_GetEndPosition ( UsefulOutBuf * me )

static

Returns position of end of data in the UsefulOutBuf.

Parameters

[in] me Pointer to the UsefulOutBuf

Returns: position of end of data

On a freshly initialized UsefulOutBuf with no data added, this will return 0. After ten bytes have been added, it will return 10 and so on.

Generally callers will not need this function for most uses of UsefulOutBuf.

Definition at line 711 of file UsefulBuf.h.

static int UsefulOutBuf_GetError ( UsefulOutBuf * me )

static

Returns the current error status.

Parameters

[in] me Pointer to the UsefulOutBuf

Returns: 0 if all OK, 1 on error

This is the error status since the call to either UsefulOutBuf_Reset() of UsefulOutBuf_Init(). Once it goes into error state it will stay until one of those functions is called.

Possible error conditions are:

bytes to be inserted will not fit
insertion point is out of buffer or past valid data
current position is off end of buffer (probably corruption or uninitialized)
detect corruption / uninitialized by bad magic number

Definition at line 1081 of file UsefulBuf.h.

void UsefulOutBuf_Init	(	UsefulOutBuf *	me,
		UsefulBuf	Storage
	)

Initialize and supply the actual output buffer.

Parameters

[out]	me	The UsefulOutBuf to initialize
[in]	Storage	Buffer to output into

Intializes the UsefulOutBuf with storage. Sets the current position to the beginning of the buffer clears the error.

This must be called before the UsefulOutBuf is used.

static void UsefulOutBuf_InsertByte	(	UsefulOutBuf *	me,
		uint8_t	byte,
		size_t	uPos
	)

static

Insert a byte into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	byte	Bytes to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a single byte is to be inserted.

Definition at line 808 of file UsefulBuf.h.

static void UsefulOutBuf_InsertData	(	UsefulOutBuf *	me,
		const void *	pBytes,
		size_t	uLen,
		size_t	uPos
	)

static

Insert a data buffer into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	pBytes	Pointer to the bytes to insert
[in]	uLen	Length of the bytes to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a pointer and length is passed in rather than an UsefulBuf.

Definition at line 778 of file UsefulBuf.h.

static void UsefulOutBuf_InsertDouble	(	UsefulOutBuf *	me,
		double	d,
		size_t	uPos
	)

static

Insert a double into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	d	Integer to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a single byte is to be inserted.

The double will be inserted in network byte order (big endian)

Definition at line 918 of file UsefulBuf.h.

static void UsefulOutBuf_InsertFloat	(	UsefulOutBuf *	me,
		float	f,
		size_t	uPos
	)

static

Insert a float into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	f	Integer to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a single byte is to be inserted.

The float will be inserted in network byte order (big endian)

Definition at line 900 of file UsefulBuf.h.

static void UsefulOutBuf_InsertString	(	UsefulOutBuf *	me,
		const char *	szString,
		size_t	uPos
	)

static

Insert a NULL-terminated string into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	szString	string to append

Definition at line 792 of file UsefulBuf.h.

static void UsefulOutBuf_InsertUint16	(	UsefulOutBuf *	me,
		uint16_t	uInteger16,
		size_t	uPos
	)

static

Insert a 16-bit integer into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	uInteger16	Integer to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a single byte is to be inserted.

The integer will be inserted in network byte order (big endian)

Definition at line 826 of file UsefulBuf.h.

static void UsefulOutBuf_InsertUint32	(	UsefulOutBuf *	me,
		uint32_t	uInteger32,
		size_t	uPos
	)

static

Insert a 32-bit integer into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	uInteger32	Integer to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a single byte is to be inserted.

The integer will be inserted in network byte order (big endian)

Definition at line 848 of file UsefulBuf.h.

static void UsefulOutBuf_InsertUint64	(	UsefulOutBuf *	me,
		uint64_t	uInteger64,
		size_t	uPos
	)

static

Insert a 64-bit integer into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBul
[in]	uInteger64	Integer to insert
[in]	uPos	Index in output buffer at which to insert

See UsefulOutBuf_InsertUsefulBuf() for details. This is the same with the difference being a single byte is to be inserted.

The integer will be inserted in network byte order (big endian)

Definition at line 872 of file UsefulBuf.h.

void UsefulOutBuf_InsertUsefulBuf	(	UsefulOutBuf *	me,
		UsefulBufC	NewData,
		size_t	uPos
	)

Inserts bytes into the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	NewData	UsefulBuf with the bytes to insert
[in]	uPos	Index in output buffer at which to insert

NewData is the pointer and length for the bytes to be added to the output buffer. There must be room in the output buffer for all of NewData or an error will occur.

The insertion point must be between 0 and the current valid data. If not an error will occur. Appending data to the output buffer is achieved by inserting at the end of the valid data. This can be retrieved by calling UsefulOutBuf_GetEndPosition().

When insertion is performed, the bytes between the insertion point and the end of data previously added to the output buffer is slid to the right to make room for the new data.

Overlapping buffers are OK. NewData can point to data in the output buffer.

If an error occurs an error state is set in the UsefulOutBuf. No error is returned. All subsequent attempts to add data will do nothing.

Call UsefulOutBuf_GetError() to find out if there is an error. This is usually not needed until all additions of data are complete.

UsefulBufC UsefulOutBuf_OutUBuf ( UsefulOutBuf * me )

Returns the resulting valid data in a UsefulOutBuf.

Parameters

[in] me Pointer to the UsefulOutBuf.

Returns: The valid data in UsefulOutBuf.

The storage for the returned data is Storage parameter passed to UsefulOutBuf_Init(). See also UsefulOutBuf_CopyOut().

This can be called anytime and many times to get intermediate results. It doesn't change the data or reset the current position so you can keep adding data.

static void UsefulOutBuf_Reset ( UsefulOutBuf * me )

static

Reset a UsefulOutBuf for re use.

Parameters

[in] me Pointer to the UsefulOutBuf

This sets the amount of data in the output buffer to none and clears the error state.

The output buffer is still the same one and size as from the UsefulOutBuf_Init() call.

It doesn't zero the data, just resets to 0 bytes of valid data.

Definition at line 689 of file UsefulBuf.h.

static size_t UsefulOutBuf_RoomLeft ( UsefulOutBuf * me )

static

Returns number of bytes unused used in the output buffer.

Parameters

[in] me Pointer to the UsefulOutBuf

Returns: Number of unused bytes or zero

Because of the error handling strategy and checks in UsefulOutBuf_InsertUsefulBuf() it is usually not necessary to use this.

Definition at line 1098 of file UsefulBuf.h.

static int UsefulOutBuf_WillItFit	(	UsefulOutBuf *	me,
		size_t	uLen
	)

static

Returns true / false if some number of bytes will fit in the UsefulOutBuf.

Parameters

[in]	me	Pointer to the UsefulOutBuf
[in]	uLen	Number of bytes for which to check

Returns: 1 or 0 if nLen bytes would fit

Because of the error handling strategy and checks in UsefulOutBuf_InsertUsefulBuf() it is usually not necessary to use this.

Definition at line 1116 of file UsefulBuf.h.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Important Information for this Arm website