summaryrefslogtreecommitdiff
path: root/README.md
blob: e6c23d0a634b5c038dd5d40d69e3da57679101be (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# array

translate files to C arrays

## Synopsis

`array [-s] [file...]`

## Description

The `array` utility translates its input into C arrays (of type
`unsigned char`) that can then be used (via `#include`) in larger C programs.
This is useful if you need to embed a binary (e.g. an image) or text (e.g.
a template) file and need to ship a program as a single, self-contained
executable.

## Options

The `array` utility conforms to the XBD Utility Syntax Guidelines. It supports
one option:

	`-s`	Include an additional identifier in the output indicating
		the size of the array. See STDOUT below for a detailed
		description.

## Operands

The `array` utility supports the following operands:

	`file`	A pathname of an input file. If `-` is specified, `array`
		reads from the standard input.

## STDIN

The standard input is used if no `file` operands are provided or if `-` is
specified as an operand.

## Input Files

Input files are treated as raw binary streams, with no requirements on format.

## STDOUT

A definition of a C array of type `unsigned char` and unspecified length, with
members initialized to the bytes of the input file. Each array is named with
the name of the input file, except all non alphanumeric characters (as
identified by the function `isalnum()`) are translated to `_`. If the input
file is the standard input, the name of the array is `stdin`.

If the `-s` option is specified, the standard output also includes the
definition of a size identifier. This identifier has the same name as the
array, suffixed with `_size`, and type `size_t`.

## STDERR

The standard error is used for printing diagnostic messages.

## Output Files

None.

## Extended Description

None.

## Exit Status

	0	Successful completion.
	>0	An error occurred.

## Consequence of Errors

If one or more input files cannot be opened, `array` will print a diagnostic
message to standard error and that file will not produe any output to
standard output.