xz-utils (5.4.5)
1 /**
2 * \file lzma/stream_flags.h
3 * \brief .xz Stream Header and Stream Footer encoder and decoder
4 * \note Never include this file directly. Use <lzma.h> instead.
5 */
6
7 /*
8 * Author: Lasse Collin
9 *
10 * This file has been put into the public domain.
11 * You can do whatever you want with this file.
12 */
13
14 #ifndef LZMA_H_INTERNAL
15 # error Never include this file directly. Use <lzma.h> instead.
16 #endif
17
18
19 /**
20 * \brief Size of Stream Header and Stream Footer
21 *
22 * Stream Header and Stream Footer have the same size and they are not
23 * going to change even if a newer version of the .xz file format is
24 * developed in future.
25 */
26 #define LZMA_STREAM_HEADER_SIZE 12
27
28
29 /**
30 * \brief Options for encoding/decoding Stream Header and Stream Footer
31 */
32 typedef struct {
33 /**
34 * \brief Stream Flags format version
35 *
36 * To prevent API and ABI breakages if new features are needed in
37 * Stream Header or Stream Footer, a version number is used to
38 * indicate which members in this structure are in use. For now,
39 * version must always be zero. With non-zero version, the
40 * lzma_stream_header_encode() and lzma_stream_footer_encode()
41 * will return LZMA_OPTIONS_ERROR.
42 *
43 * lzma_stream_header_decode() and lzma_stream_footer_decode()
44 * will always set this to the lowest value that supports all the
45 * features indicated by the Stream Flags field. The application
46 * must check that the version number set by the decoding functions
47 * is supported by the application. Otherwise it is possible that
48 * the application will decode the Stream incorrectly.
49 */
50 uint32_t version;
51
52 /**
53 * \brief Backward Size
54 *
55 * Backward Size must be a multiple of four bytes. In this Stream
56 * format version, Backward Size is the size of the Index field.
57 *
58 * Backward Size isn't actually part of the Stream Flags field, but
59 * it is convenient to include in this structure anyway. Backward
60 * Size is present only in the Stream Footer. There is no need to
61 * initialize backward_size when encoding Stream Header.
62 *
63 * lzma_stream_header_decode() always sets backward_size to
64 * LZMA_VLI_UNKNOWN so that it is convenient to use
65 * lzma_stream_flags_compare() when both Stream Header and Stream
66 * Footer have been decoded.
67 */
68 lzma_vli backward_size;
69
70 /**
71 * \brief Minimum value for lzma_stream_flags.backward_size
72 */
73 # define LZMA_BACKWARD_SIZE_MIN 4
74
75 /**
76 * \brief Maximum value for lzma_stream_flags.backward_size
77 */
78 # define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34)
79
80 /**
81 * \brief Check ID
82 *
83 * This indicates the type of the integrity check calculated from
84 * uncompressed data.
85 */
86 lzma_check check;
87
88 /*
89 * Reserved space to allow possible future extensions without
90 * breaking the ABI. You should not touch these, because the
91 * names of these variables may change.
92 *
93 * (We will never be able to use all of these since Stream Flags
94 * is just two bytes plus Backward Size of four bytes. But it's
95 * nice to have the proper types when they are needed.)
96 */
97
98 /** \private Reserved member. */
99 lzma_reserved_enum reserved_enum1;
100
101 /** \private Reserved member. */
102 lzma_reserved_enum reserved_enum2;
103
104 /** \private Reserved member. */
105 lzma_reserved_enum reserved_enum3;
106
107 /** \private Reserved member. */
108 lzma_reserved_enum reserved_enum4;
109
110 /** \private Reserved member. */
111 lzma_bool reserved_bool1;
112
113 /** \private Reserved member. */
114 lzma_bool reserved_bool2;
115
116 /** \private Reserved member. */
117 lzma_bool reserved_bool3;
118
119 /** \private Reserved member. */
120 lzma_bool reserved_bool4;
121
122 /** \private Reserved member. */
123 lzma_bool reserved_bool5;
124
125 /** \private Reserved member. */
126 lzma_bool reserved_bool6;
127
128 /** \private Reserved member. */
129 lzma_bool reserved_bool7;
130
131 /** \private Reserved member. */
132 lzma_bool reserved_bool8;
133
134 /** \private Reserved member. */
135 uint32_t reserved_int1;
136
137 /** \private Reserved member. */
138 uint32_t reserved_int2;
139
140 } lzma_stream_flags;
141
142
143 /**
144 * \brief Encode Stream Header
145 *
146 * \param options Stream Header options to be encoded.
147 * options->backward_size is ignored and doesn't
148 * need to be initialized.
149 * \param[out] out Beginning of the output buffer of
150 * LZMA_STREAM_HEADER_SIZE bytes.
151 *
152 * \return Possible lzma_ret values:
153 * - LZMA_OK: Encoding was successful.
154 * - LZMA_OPTIONS_ERROR: options->version is not supported by
155 * this liblzma version.
156 * - LZMA_PROG_ERROR: Invalid options.
157 */
158 extern LZMA_API(lzma_ret) lzma_stream_header_encode(
159 const lzma_stream_flags *options, uint8_t *out)
160 lzma_nothrow lzma_attr_warn_unused_result;
161
162
163 /**
164 * \brief Encode Stream Footer
165 *
166 * \param options Stream Footer options to be encoded.
167 * \param[out] out Beginning of the output buffer of
168 * LZMA_STREAM_HEADER_SIZE bytes.
169 *
170 * \return Possible lzma_ret values:
171 * - LZMA_OK: Encoding was successful.
172 * - LZMA_OPTIONS_ERROR: options->version is not supported by
173 * this liblzma version.
174 * - LZMA_PROG_ERROR: Invalid options.
175 */
176 extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
177 const lzma_stream_flags *options, uint8_t *out)
178 lzma_nothrow lzma_attr_warn_unused_result;
179
180
181 /**
182 * \brief Decode Stream Header
183 *
184 * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to
185 * help comparing Stream Flags from Stream Header and Stream Footer with
186 * lzma_stream_flags_compare().
187 *
188 * \note When decoding .xz files that contain multiple Streams, it may
189 * make sense to print "file format not recognized" only if
190 * decoding of the Stream Header of the \a first Stream gives
191 * LZMA_FORMAT_ERROR. If non-first Stream Header gives
192 * LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is
193 * probably more appropriate.
194 * For example, the Stream decoder in liblzma uses
195 * LZMA_DATA_ERROR if LZMA_FORMAT_ERROR is returned by
196 * lzma_stream_header_decode() when decoding non-first Stream.
197 *
198 * \param[out] options Target for the decoded Stream Header options.
199 * \param in Beginning of the input buffer of
200 * LZMA_STREAM_HEADER_SIZE bytes.
201 *
202 *
203 * \return Possible lzma_ret values:
204 * - LZMA_OK: Decoding was successful.
205 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
206 * buffer cannot be Stream Header.
207 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header
208 * is corrupt.
209 * - LZMA_OPTIONS_ERROR: Unsupported options are present
210 * in the header.
211 */
212 extern LZMA_API(lzma_ret) lzma_stream_header_decode(
213 lzma_stream_flags *options, const uint8_t *in)
214 lzma_nothrow lzma_attr_warn_unused_result;
215
216
217 /**
218 * \brief Decode Stream Footer
219 *
220 * \note If Stream Header was already decoded successfully, but
221 * decoding Stream Footer returns LZMA_FORMAT_ERROR, the
222 * application should probably report some other error message
223 * than "file format not recognized". The file likely
224 * is corrupt (possibly truncated). The Stream decoder in liblzma
225 * uses LZMA_DATA_ERROR in this situation.
226 *
227 * \param[out] options Target for the decoded Stream Footer options.
228 * \param in Beginning of the input buffer of
229 * LZMA_STREAM_HEADER_SIZE bytes.
230 *
231 * \return Possible lzma_ret values:
232 * - LZMA_OK: Decoding was successful.
233 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
234 * buffer cannot be Stream Footer.
235 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer
236 * is corrupt.
237 * - LZMA_OPTIONS_ERROR: Unsupported options are present
238 * in Stream Footer.
239 */
240 extern LZMA_API(lzma_ret) lzma_stream_footer_decode(
241 lzma_stream_flags *options, const uint8_t *in)
242 lzma_nothrow lzma_attr_warn_unused_result;
243
244
245 /**
246 * \brief Compare two lzma_stream_flags structures
247 *
248 * backward_size values are compared only if both are not
249 * LZMA_VLI_UNKNOWN.
250 *
251 * \param a Pointer to lzma_stream_flags structure
252 * \param b Pointer to lzma_stream_flags structure
253 *
254 * \return Possible lzma_ret values:
255 * - LZMA_OK: Both are equal. If either had backward_size set
256 * to LZMA_VLI_UNKNOWN, backward_size values were not
257 * compared or validated.
258 * - LZMA_DATA_ERROR: The structures differ.
259 * - LZMA_OPTIONS_ERROR: version in either structure is greater
260 * than the maximum supported version (currently zero).
261 * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or
262 * backward_size.
263 */
264 extern LZMA_API(lzma_ret) lzma_stream_flags_compare(
265 const lzma_stream_flags *a, const lzma_stream_flags *b)
266 lzma_nothrow lzma_attr_pure;
Browse
Usage
Versions