NAME

carray — convert binary file to C array

SYNOPSIS

DESCRIPTION

carray encodes its input as the source code for a C array of hexadecimal constants. The input is the specified file operands concatenated, or the standard input if no input files are specified. carray writes the source code for a C array to the standard output, or output if the -o option is given. The default type is an array of unsigned char. The array contents are indented with tabs and the lines don't exceed 80 columns (tabs have the width of 8 spaces).

The default array name is the output path if set, or the path of the first input file (if any), or otherwise carray. The default array name has all file extensions removed (but a leading period in the file name is kept). The default array name is converted to the characters a-z, A-Z, ‘_’, and 0-9. 0-9 cannot be the first character of an identifier. ‘+’ will be replaced by ‘x’. Any other characters are replaced by ‘_’ unless it is the first character, in which case it is replaced by ‘x’.

A guard macro is optionally used by the -g and -G options. The default guard macro is the output path if set, or the path of the first input file (if any) followed by _H, or otherwise CARRAY_H. The default guard macro is converted to the characters A-Z, ‘_’, and 0-9. 0-9 cannot be the first character of an identifier. The lower-case a-z is converted to the upper-case A-Z. ‘+’ is replaced by ‘X’. Any other characters are replaced by ‘_’.

Parts of the output are optional, but the output will be in this order: The opening guard macro check, the guard macro definition, the inclusion of prerequisite headers, the opening extern "C" block, the array declaration and initialization, the closing extern "C" block, and the closing guard macro check.

The options are as follows:

-c, --const

Declare the array with the const keyword.

-e, --extern

Declare the array with the extern keyword. This option is mutually incompatible with the -s option.

-E, --extern-c

Wrap the array in extern "C" { } subject to a preprocessor check for C++.

-f, --forward

Forward declare the array only, do not initialize it with contents. The input files are not opened and the standard input is unused. This option is mutually incompatible with the -r option.

-g, --use-guard

Wrap the output in a preprocessor conditional checking the guard macro is not set, and declare the macro if it is not set. This conditional is a classic C include guard that ensures only the first inclusion of a header has any effect.

-G, --guard guard

Sets the guard macro to guard and enables the guard macro check as if the -g option was set as well. The guard macro is unrestricted and untransformed and will be output verbatim.

-H, --headers

Output inclusions of all the prerequisite headers. By default, there are no prerequisite headers, unless the array type is one of the <stdint.h> types, in which case <stdint.h> is the only prerequisite header.

--identifier identifier

Sets the name of the array to identifier. The identifier is unrestricted and will be output verbatim.

--includes include-statements

Sets the C preprocessor statements include-statements as how to include all the prerequisite headers and enables inclusion of the prerequisite headers as if the -H option was set. The preprocessor statements are unrestricted and untransformed and will be output verbatim.

-o, -output output

Write the output to the output path rather than the standard output.

-r, --raw

Output only the hexadecimally encoded array contents, and the guard macro check if set by the -g option. This option is mutually incompatible with the -f option.

-s, --static

Declare the array with the static keyword.

-t, --type type

Declare the array as an array of the specified type. The type is unrestricted and will be output verbatim.

-v, --volatile

Declare the array with the volatile keyword.

In addition to the -t option, the array type can be set by the following options:

--char

Declare as array of char.

--signed-char

Declare as array of signed char.

--unsigned-char

Declare as array of unsigned char.

--int8_t

Declare as array of int8_t.

--uint8_t

Declare as array of uint8_t.

EXIT STATUS

carray will exit 0 on success and non-zero otherwise.

EXAMPLES

$ echo foo | carray
unsigned char carray[] = {
	0x66, 0x6F, 0x6F, 0x0A,
};

$ echo foo | carray -cs -o foo.inc
$ cat foo.inc
static const unsigned char foo[] = {
	0x66, 0x6F, 0x6F, 0x0A,
};

$ echo foo | carray -ceEfgH -t uint8_t -o foo.h
$ cat foo.h
#ifndef FOO_H
#define FOO_H

#include <stdint.h>

#if defined(__cplusplus)
extern "C" {
#endif

extern const uint8_t foo[];

#if defined(__cplusplus)
} /* extern "C" */
#endif

#endif

$ echo foo | carray -cH -t uint8_t -o foo.c
$ cat foo.c
#include <stdint.h>

const uint8_t foo[] = {
	0x66, 0x6F, 0x6F, 0x0A,
};

$ echo foo | carray -r
	0x66, 0x6F, 0x6F, 0x0A,

SEE ALSO

gcc(1)