bufdumplib.h File Reference

This library provides a C API for hexadecimal dumps and diffs of binary memory buffers. More...

Go to the source code of this file.

Functions
int	bufdumplib_dump (FILE *fp, const void *buf, size_t len, int flags)
	Write a hex dump of a binary memory buffer over the specified length into a file pointer. More...
int	bufdumplib_diff (FILE *fp, const void *b0, const void *b1, size_t len, int flags)
	Write a hex diff of two binary memory buffers over the specified length into a file pointer. More...
int	bufdumplib_text (FILE *fp, const void *buf, size_t len)
	Write a comma-delimited hex byte array (e.g. for use in C source) into a file pointer. More...

Detailed Description

This library provides a C API for hexadecimal dumps and diffs of binary memory buffers.

Function Documentation

bufdumplib_dump()

int bufdumplib_dump	(	FILE *	fp,
		const void *	buf,
		size_t	len,
		int	flags
	)

Write a hex dump of a binary memory buffer over the specified length into a file pointer.

Parameters

fp	FILE pointer to which to write output
buf	Buffer data to dump
len	Length of buffer
flags	1 skips all-zero lines (of 16 bytes) 2 skips all-zero groups (of 4 bytes) 4 skips individual zero bytes

Returns

On success, count of non-skipped bytes printed. On error, a negative value.

Examples
Given the following C data buffer:

    uint8_t const buf[] = {
0xfe,0xed,0xfa,0xce,0xde,0xad,0xbe,0xef,   0,   0,   0,   0,   0,   0,   0,   0,
   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
   0,0xde,0xad,0xfa,0xce,   0,   0,   0,   0,   0,   0,   0,0xde,0xad,0xfa,0xce,
    };

bufdumplib_dump(stdout, buf, sizeof buf, 0) with flags=0 outputs:

000000: feedface deadbeef 00000000 00000000
000010: 00000000 00000000 00000000 00000000
000020: 00000000 00000000 00000000 00000000
000030: 00deadfa ce000000 00000000 deadface

bufdumplib_dump(stdout, buf, sizeof buf, 1) with flags=1 skips the first and second lines since they contain only zeros:

000000: feedface deadbeef 00000000 00000000
000030: 00deadfa ce000000 00000000 deadface

bufdumplib_dump(stdout, buf, sizeof buf, 2) with flags=2 blanks the 4 byte (32 bit) zero groups:

000000: feedface deadbeef ........ ........
000010: ........ ........ ........ ........
000020: ........ ........ ........ ........
000030: 00deadfa ce000000 ........ deadface

bufdumplib_dump(stdout, buf, sizeof buf, 4) with flags=4 blanks the remaining individual zero bytes in line 4 that the previous example left in numeric form:

000000: feedface deadbeef ........ ........
000010: ........ ........ ........ ........
000020: ........ ........ ........ ........
000030: ..deadfa ce...... ........ deadface

bufdumplib_dump(stdout, buf, sizeof buf, 3) with flags=3 blanks lines and groups that are zero, but preserves the individual zero bytes on line 4:

000000: feedface deadbeef ........ ........
000030: 00deadfa ce000000 ........ deadface

This example can be found in examples/dumpexample.c

bufdumplib_diff()

int bufdumplib_diff	(	FILE *	fp,
		const void *	b0,
		const void *	b1,
		size_t	len,
		int	flags
	)

Write a hex diff of two binary memory buffers over the specified length into a file pointer.

Parameters

fp	FILE pointer to which to write output
b0	First buffer to compare (output on left)
b1	Second buffer to compare (output on right)
len	Length of buffer
flags	1 skips identical lines (of 16 bytes) 2 skips identical groups (of 4 bytes) 4 skips identical bytes

Returns

On success, count of non-skipped bytes printed. On error, a negative value.

Examples
Now consider a new buffer with a few changed bytes:

    uint8_t const chg[] = {
0xfe,0xed,0xfa,0xce,0xbe,0xef,0xbe,0xef,   0,   0,   0,   0,   0,   0,   0,   0,
//                    ^^   ^^
   0,   0,0x03,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
//          ^^
   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
   0,0xde,0xad,0xfa,0xce,   0,   0,   0,   0,   0,   0,   0,0xde,0xad,0xfa,0xce,
    };

bufdumplib_diff(stdout, buf, chg, sizeof buf, 0) with flags=0 outputs a straight comparison with everything intact:

000000: feedface deadbeef 00000000 00000000|feedface beefbeef 00000000 00000000
000010: 00000000 00000000 00000000 00000000|00000300 00000000 00000000 00000000
000020: 00000000 00000000 00000000 00000000|00000000 00000000 00000000 00000000
000030: 00deadfa ce000000 00000000 deadface|00deadfa ce000000 00000000 deadface

bufdumplib_diff(stdout, buf, chg, sizeof buf, 1) with flags=1 skips the second and third lines since they are the same:

000000: feedface deadbeef 00000000 00000000|feedface beefbeef 00000000 00000000
000010: 00000000 00000000 00000000 00000000|00000300 00000000 00000000 00000000

bufdumplib_diff(stdout, buf, chg, sizeof buf, 2) with flags=2 blanks the 4 byte (32 bit) groups that are the same in each buffer:

000000: ........ deadbeef ........ ........|........ beefbeef ........ ........
000010: 00000000 ........ ........ ........|00000300 ........ ........ ........
000020: ........ ........ ........ ........|........ ........ ........ ........
000030: ........ ........ ........ ........|........ ........ ........ ........

bufdumplib_diff(stdout, buf, chg, sizeof buf, 4) with flags=4 blanks the remaining individual zero bytes in lines 0 and 1 that the previous example left in numeric form:

000000: ........ dead.... ........ ........|........ beef.... ........ ........
000010: ....00.. ........ ........ ........|....03.. ........ ........ ........
000020: ........ ........ ........ ........|........ ........ ........ ........
000030: ........ ........ ........ ........|........ ........ ........ ........

bufdumplib_diff(stdout, buf, chg, sizeof buf, 7) with flags=7 (or 5) blanks lines and bytes (and groups) that are the same:

000000: ........ dead.... ........ ........|........ beef.... ........ ........
000010: ....00.. ........ ........ ........|....03.. ........ ........ ........

This example can be found in examples/diffexample.c

bufdumplib_text()

int bufdumplib_text	(	FILE *	fp,
		const void *	buf,
		size_t	len
	)

Write a comma-delimited hex byte array (e.g. for use in C source) into a file pointer.

Parameters

fp	FILE pointer to which to write output
buf	Buffer data to dump
len	Length of buffer

Returns

On success, count of byte array. On error, a negative value.

Example
Given the same C data buffer as above:

    uint8_t const buf[] = {
0xfe,0xed,0xfa,0xce,0xde,0xad,0xbe,0xef,   0,   0,   0,   0,   0,   0,   0,   0,
   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
   0,0xde,0xad,0xfa,0xce,   0,   0,   0,   0,   0,   0,   0,0xde,0xad,0xfa,0xce,
    };

bufdumplib_text(stdout, buf, sizeof buf) outputs:

0xfe,0xed,0xfa,0xce,0xde,0xad,0xbe,0xef,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0xde,0xad,0xfa,0xce,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xde,0xad,0xfa,0xce

This example can be found in examples/textexample.c