CARRAY(1)

NAME
carray - convert binary file to C array

SYNOPSIS
carray [-ceEgHrsv] [-G guard] [--identifier=identifier] [--includes=include-statements] [-o output] [-t type] [file ...]

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)