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