Sortix 1.1dev ports manual

This manual documents Sortix 1.1dev ports. You can instead view this document in the latest official manual.

CARRAY(1)

General Commands Manual

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,