VirtualBox

source: vbox/trunk/include/iprt/zip.h@ 103224

Last change on this file since 103224 was 98732, checked in by vboxsync, 20 months ago

Config.kmk,Runtime: Add support for xz archives using liblzma-5.4.1, bugref:10254

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.5 KB
Line 
1/** @file
2 * IPRT - Compression.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_zip_h
37#define IPRT_INCLUDED_zip_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44
45RT_C_DECLS_BEGIN
46
47/** @defgroup grp_rt_zip RTZip - Compression
48 * @ingroup grp_rt
49 * @{
50 */
51
52
53
54/**
55 * Callback function for consuming compressed data during compression.
56 *
57 * @returns iprt status code.
58 * @param pvUser User argument.
59 * @param pvBuf Compressed data.
60 * @param cbBuf Size of the compressed data.
61 */
62typedef DECLCALLBACKTYPE(int, FNRTZIPOUT,(void *pvUser, const void *pvBuf, size_t cbBuf));
63/** Pointer to FNRTZIPOUT() function. */
64typedef FNRTZIPOUT *PFNRTZIPOUT;
65
66/**
67 * Callback function for supplying compressed data during decompression.
68 *
69 * @returns iprt status code.
70 * @param pvUser User argument.
71 * @param pvBuf Where to store the compressed data.
72 * @param cbBuf Size of the buffer.
73 * @param pcbBuf Number of bytes actually stored in the buffer.
74 */
75typedef DECLCALLBACKTYPE(int, FNRTZIPIN,(void *pvUser, void *pvBuf, size_t cbBuf, size_t *pcbBuf));
76/** Pointer to FNRTZIPIN() function. */
77typedef FNRTZIPIN *PFNRTZIPIN;
78
79/**
80 * Compression type.
81 * (Be careful with these they are stored in files!)
82 */
83typedef enum RTZIPTYPE
84{
85 /** Invalid. */
86 RTZIPTYPE_INVALID = 0,
87 /** Choose best fitting one. */
88 RTZIPTYPE_AUTO,
89 /** Store the data. */
90 RTZIPTYPE_STORE,
91 /** Zlib compression the data. */
92 RTZIPTYPE_ZLIB,
93 /** BZlib compress. */
94 RTZIPTYPE_BZLIB,
95 /** libLZF compress. */
96 RTZIPTYPE_LZF,
97 /** Lempel-Ziv-Jeff-Bonwick compression. */
98 RTZIPTYPE_LZJB,
99 /** Lempel-Ziv-Oberhumer compression. */
100 RTZIPTYPE_LZO,
101 /* Zlib compression the data without zlib header. */
102 RTZIPTYPE_ZLIB_NO_HEADER,
103 /** End of valid the valid compression types. */
104 RTZIPTYPE_END
105} RTZIPTYPE;
106
107/**
108 * Compression level.
109 */
110typedef enum RTZIPLEVEL
111{
112 /** Store, don't compress. */
113 RTZIPLEVEL_STORE = 0,
114 /** Fast compression. */
115 RTZIPLEVEL_FAST,
116 /** Default compression. */
117 RTZIPLEVEL_DEFAULT,
118 /** Maximal compression. */
119 RTZIPLEVEL_MAX
120} RTZIPLEVEL;
121
122
123/**
124 * Create a stream compressor instance.
125 *
126 * @returns iprt status code.
127 * @param ppZip Where to store the instance handle.
128 * @param pvUser User argument which will be passed on to pfnOut and pfnIn.
129 * @param pfnOut Callback for consuming output of compression.
130 * @param enmType Type of compressor to create.
131 * @param enmLevel Compression level.
132 */
133RTDECL(int) RTZipCompCreate(PRTZIPCOMP *ppZip, void *pvUser, PFNRTZIPOUT pfnOut, RTZIPTYPE enmType, RTZIPLEVEL enmLevel);
134
135/**
136 * Compresses a chunk of memory.
137 *
138 * @returns iprt status code.
139 * @param pZip The compressor instance.
140 * @param pvBuf Pointer to buffer containing the bits to compress.
141 * @param cbBuf Number of bytes to compress.
142 */
143RTDECL(int) RTZipCompress(PRTZIPCOMP pZip, const void *pvBuf, size_t cbBuf);
144
145/**
146 * Finishes the compression.
147 * This will flush all data and terminate the compression data stream.
148 *
149 * @returns iprt status code.
150 * @param pZip The stream compressor instance.
151 */
152RTDECL(int) RTZipCompFinish(PRTZIPCOMP pZip);
153
154/**
155 * Destroys the stream compressor instance.
156 *
157 * @returns iprt status code.
158 * @param pZip The compressor instance.
159 */
160RTDECL(int) RTZipCompDestroy(PRTZIPCOMP pZip);
161
162
163/**
164 * Create a stream decompressor instance.
165 *
166 * @returns iprt status code.
167 * @param ppZip Where to store the instance handle.
168 * @param pvUser User argument which will be passed on to pfnOut and pfnIn.
169 * @param pfnIn Callback for producing input for decompression.
170 */
171RTDECL(int) RTZipDecompCreate(PRTZIPDECOMP *ppZip, void *pvUser, PFNRTZIPIN pfnIn);
172
173/**
174 * Decompresses a chunk of memory.
175 *
176 * @returns iprt status code.
177 * @param pZip The stream decompressor instance.
178 * @param pvBuf Where to store the decompressed data.
179 * @param cbBuf Number of bytes to produce. If pcbWritten is set
180 * any number of bytes up to cbBuf might be returned.
181 * @param pcbWritten Number of bytes actually written to the buffer. If NULL
182 * cbBuf number of bytes must be written.
183 */
184RTDECL(int) RTZipDecompress(PRTZIPDECOMP pZip, void *pvBuf, size_t cbBuf, size_t *pcbWritten);
185
186/**
187 * Destroys the stream decompressor instance.
188 *
189 * @returns iprt status code.
190 * @param pZip The decompressor instance.
191 */
192RTDECL(int) RTZipDecompDestroy(PRTZIPDECOMP pZip);
193
194
195/**
196 * Compress a chunk of memory into a block.
197 *
198 * @returns IPRT status code.
199 *
200 * @param enmType The compression type.
201 * @param enmLevel The compression level.
202 * @param fFlags Flags reserved for future extensions, MBZ.
203 * @param pvSrc Pointer to the input block.
204 * @param cbSrc Size of the input block.
205 * @param pvDst Pointer to the output buffer.
206 * @param cbDst The size of the output buffer.
207 * @param pcbDstActual Where to return the compressed size.
208 */
209RTDECL(int) RTZipBlockCompress(RTZIPTYPE enmType, RTZIPLEVEL enmLevel, uint32_t fFlags,
210 void const *pvSrc, size_t cbSrc,
211 void *pvDst, size_t cbDst, size_t *pcbDstActual) RT_NO_THROW_PROTO;
212
213
214/**
215 * Decompress a block.
216 *
217 * @returns IPRT status code.
218 *
219 * @param enmType The compression type.
220 * @param fFlags Flags reserved for future extensions, MBZ.
221 * @param pvSrc Pointer to the input block.
222 * @param cbSrc Size of the input block.
223 * @param pcbSrcActual Where to return the compressed size.
224 * @param pvDst Pointer to the output buffer.
225 * @param cbDst The size of the output buffer.
226 * @param pcbDstActual Where to return the decompressed size.
227 */
228RTDECL(int) RTZipBlockDecompress(RTZIPTYPE enmType, uint32_t fFlags,
229 void const *pvSrc, size_t cbSrc, size_t *pcbSrcActual,
230 void *pvDst, size_t cbDst, size_t *pcbDstActual) RT_NO_THROW_PROTO;
231
232
233/**
234 * Opens a gzip decompression I/O stream.
235 *
236 * @returns IPRT status code.
237 *
238 * @param hVfsIosIn The compressed input stream (must be readable).
239 * The reference is not consumed, instead another
240 * one is retained.
241 * @param fFlags Flags, MBZ.
242 * @param phVfsIosGunzip Where to return the handle to the gunzipped I/O
243 * stream (read).
244 */
245RTDECL(int) RTZipGzipDecompressIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSIOSTREAM phVfsIosGunzip);
246
247/** @name RTZipGzipDecompressIoStream flags.
248 * @{ */
249/** Allow the smaller ZLIB header as well as the regular GZIP header. */
250#define RTZIPGZIPDECOMP_F_ALLOW_ZLIB_HDR RT_BIT(0)
251/** @} */
252
253
254/**
255 * Opens a xz decompression I/O stream.
256 *
257 * @returns IPRT status code.
258 *
259 * @param hVfsIosIn The compressed input stream (must be readable).
260 * The reference is not consumed, instead another
261 * one is retained.
262 * @param fFlags Flags, MBZ.
263 * @param phVfsIosXz Where to return the handle to the decompressed I/O
264 * stream (read).
265 */
266RTDECL(int) RTZipXzDecompressIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSIOSTREAM phVfsIosXz);
267
268
269/**
270 * Opens a gzip decompression I/O stream.
271 *
272 * @returns IPRT status code.
273 *
274 * @param hVfsIosDst The compressed output stream (must be writable).
275 * The reference is not consumed, instead another
276 * one is retained.
277 * @param fFlags Flags, MBZ.
278 * @param uLevel The gzip compression level, 1 thru 9.
279 * @param phVfsIosGzip Where to return the gzip input I/O stream handle
280 * (you write to this).
281 */
282RTDECL(int) RTZipGzipCompressIoStream(RTVFSIOSTREAM hVfsIosDst, uint32_t fFlags, uint8_t uLevel, PRTVFSIOSTREAM phVfsIosGzip);
283
284
285/**
286 * Opens a xz decompression I/O stream.
287 *
288 * @returns IPRT status code.
289 *
290 * @param hVfsIosDst The compressed output stream (must be writable).
291 * The reference is not consumed, instead another
292 * one is retained.
293 * @param fFlags Flags, MBZ.
294 * @param uLevel The xz compression level, 1 thru 9.
295 * @param phVfsIosXz Where to return the xz input I/O stream handle
296 * (you write to this).
297 */
298RTDECL(int) RTZipXzCompressIoStream(RTVFSIOSTREAM hVfsIosDst, uint32_t fFlags, uint8_t uLevel, PRTVFSIOSTREAM phVfsIosXz);
299
300
301/**
302 * A mini GZIP program.
303 *
304 * @returns Program exit code.
305 *
306 * @param cArgs The number of arguments.
307 * @param papszArgs The argument vector. (Note that this may be
308 * reordered, so the memory must be writable.)
309 */
310RTDECL(RTEXITCODE) RTZipGzipCmd(unsigned cArgs, char **papszArgs);
311
312/**
313 * Opens a TAR filesystem stream.
314 *
315 * This is used to extract, list or check a TAR archive.
316 *
317 * @returns IPRT status code.
318 *
319 * @param hVfsIosIn The input stream. The reference is not
320 * consumed, instead another one is retained.
321 * @param fFlags Flags, MBZ.
322 * @param phVfsFss Where to return the handle to the TAR
323 * filesystem stream.
324 */
325RTDECL(int) RTZipTarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
326
327/** TAR format type. */
328typedef enum RTZIPTARFORMAT
329{
330 /** Customary invalid zero value. */
331 RTZIPTARFORMAT_INVALID = 0,
332 /** Default format (GNU). */
333 RTZIPTARFORMAT_DEFAULT,
334 /** The GNU format. */
335 RTZIPTARFORMAT_GNU,
336 /** USTAR format from POSIX.1-1988. */
337 RTZIPTARFORMAT_USTAR,
338 /** PAX format from POSIX.1-2001. */
339 RTZIPTARFORMAT_PAX,
340 /** CPIO format (portable ASCII foramt as defined by SuSV2). */
341 RTZIPTARFORMAT_CPIO_ASCII_SUSV2,
342 /** CPIO format (New ascii format). */
343 RTZIPTARFORMAT_CPIO_ASCII_NEW,
344 /** CPIO format (New ascii format with checksumming). */
345 RTZIPTARFORMAT_CPIO_ASCII_NEW_CHKSUM,
346 /** End of valid formats. */
347 RTZIPTARFORMAT_END,
348 /** Make sure the type is at least 32 bits wide. */
349 RTZIPTARFORMAT_32BIT_HACK = 0x7fffffff
350} RTZIPTARFORMAT;
351
352/**
353 * Opens a TAR filesystem stream for the purpose of create a new TAR archive.
354 *
355 * @returns IPRT status code.
356 *
357 * @param hVfsIosOut The output stream, i.e. where the tar stuff is
358 * written. The reference is not consumed, instead
359 * another one is retained.
360 * @param enmFormat The desired output format.
361 * @param fFlags RTZIPTAR_C_XXX, except RTZIPTAR_C_UPDATE.
362 * @param phVfsFss Where to return the handle to the TAR
363 * filesystem stream.
364 */
365RTDECL(int) RTZipTarFsStreamToIoStream(RTVFSIOSTREAM hVfsIosOut, RTZIPTARFORMAT enmFormat,
366 uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
367
368/** @name RTZIPTAR_C_XXX - TAR creation flags (RTZipTarFsStreamToIoStream).
369 * @{ */
370/** Check for sparse files.
371 * @note Only supported when adding file objects. The files will be read
372 * twice. */
373#define RTZIPTAR_C_SPARSE RT_BIT_32(0)
374/** Set if opening for updating. */
375#define RTZIPTAR_C_UPDATE RT_BIT_32(1)
376/** Valid bits. */
377#define RTZIPTAR_C_VALID_MASK UINT32_C(0x00000003)
378/** @} */
379
380/**
381 * Opens a TAR filesystem stream for the purpose of create a new TAR archive or
382 * updating an existing one.
383 *
384 * @returns IPRT status code.
385 *
386 * @param hVfsFile The TAR file handle, i.e. where the tar stuff is
387 * written and optionally read/update. The
388 * reference is not consumed, instead another one
389 * is retained.
390 * @param enmFormat The desired output format.
391 * @param fFlags RTZIPTAR_C_XXX.
392 * @param phVfsFss Where to return the handle to the TAR
393 * filesystem stream.
394 */
395RTDECL(int) RTZipTarFsStreamForFile(RTVFSFILE hVfsFile, RTZIPTARFORMAT enmFormat, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
396
397/**
398 * Set the owner to store the archive entries with.
399 *
400 * @returns IPRT status code.
401 * @param hVfsFss The handle to a TAR creator.
402 * @param uid The UID value to set. Passing NIL_RTUID makes
403 * it use the value found in RTFSOBJINFO.
404 * @param pszOwner The owner name to store. Passing NULL makes it
405 * use the value found in RTFSOBJINFO.
406 */
407RTDECL(int) RTZipTarFsStreamSetOwner(RTVFSFSSTREAM hVfsFss, RTUID uid, const char *pszOwner);
408
409/**
410 * Set the group to store the archive entries with.
411 *
412 * @returns IPRT status code.
413 * @param hVfsFss The handle to a TAR creator.
414 * @param gid The GID value to set. Passing NIL_RTUID makes
415 * it use the value found in RTFSOBJINFO.
416 * @param pszGroup The group name to store. Passing NULL makes it
417 * use the value found in RTFSOBJINFO.
418 */
419RTDECL(int) RTZipTarFsStreamSetGroup(RTVFSFSSTREAM hVfsFss, RTGID gid, const char *pszGroup);
420
421/**
422 * Set path prefix to store the archive entries with.
423 *
424 * @returns IPRT status code.
425 * @param hVfsFss The handle to a TAR creator.
426 * @param pszPrefix The path prefix to join the names with. Pass
427 * NULL for no prefix.
428 */
429RTDECL(int) RTZipTarFsStreamSetPrefix(RTVFSFSSTREAM hVfsFss, const char *pszPrefix);
430
431/**
432 * Set the AND and OR masks to apply to file (non-dir) modes in the archive.
433 *
434 * @returns IPRT status code.
435 * @param hVfsFss The handle to a TAR creator.
436 * @param fAndMode The bits to keep
437 * @param fOrMode The bits to set.
438 */
439RTDECL(int) RTZipTarFsStreamSetFileMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
440
441/**
442 * Set the AND and OR masks to apply to directory modes in the archive.
443 *
444 * @returns IPRT status code.
445 * @param hVfsFss The handle to a TAR creator.
446 * @param fAndMode The bits to keep
447 * @param fOrMode The bits to set.
448 */
449RTDECL(int) RTZipTarFsStreamSetDirMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
450
451/**
452 * Set the modification time to store the archive entires with.
453 *
454 * @returns IPRT status code.
455 * @param hVfsFss The handle to a TAR creator.
456 * @param pModificationTime The modification time to use. Pass NULL to use
457 * the value found in RTFSOBJINFO.
458 */
459RTDECL(int) RTZipTarFsStreamSetMTime(RTVFSFSSTREAM hVfsFss, PCRTTIMESPEC pModificationTime);
460
461/**
462 * Truncates a TAR creator stream in update mode.
463 *
464 * Use RTVfsFsStrmNext to examine the TAR stream and locate the cut-off point.
465 *
466 * After performing this call, the stream will be in write mode and
467 * RTVfsFsStrmNext will stop working (VERR_WRONG_ORDER). The RTVfsFsStrmAdd()
468 * and RTVfsFsStrmPushFile() can be used to add new object to the TAR file,
469 * starting at the trunction point. RTVfsFsStrmEnd() is used to finish the TAR
470 * file (this performs the actual file trunction).
471 *
472 * @returns IPRT status code.
473 * @param hVfsFss The handle to a TAR creator in update mode.
474 * @param hVfsObj Object returned by RTVfsFsStrmNext that the
475 * trunction is relative to. This doesn't have to
476 * be the current stream object, it can be an
477 * earlier one too.
478 * @param fAfter If set, @a hVfsObj will remain in the update TAR
479 * file. If clear, @a hVfsObj will not be
480 * included.
481 */
482RTDECL(int) RTZipTarFsStreamTruncate(RTVFSFSSTREAM hVfsFss, RTVFSOBJ hVfsObj, bool fAfter);
483
484/**
485 * A mini TAR program.
486 *
487 * @returns Program exit code.
488 *
489 * @param cArgs The number of arguments.
490 * @param papszArgs The argument vector. (Note that this may be
491 * reordered, so the memory must be writable.)
492 */
493RTDECL(RTEXITCODE) RTZipTarCmd(unsigned cArgs, char **papszArgs);
494
495/**
496 * Opens a ZIP filesystem stream.
497 *
498 * This is used to extract, list or check a ZIP archive.
499 *
500 * @returns IPRT status code.
501 *
502 * @param hVfsIosIn The compressed input stream. The reference is
503 * not consumed, instead another one is retained.
504 * @param fFlags Flags, MBZ.
505 * @param phVfsFss Where to return the handle to the TAR
506 * filesystem stream.
507 */
508RTDECL(int) RTZipPkzipFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
509
510/**
511 * A mini UNZIP program.
512 *
513 * @returns Program exit code.
514 * @
515 * @param cArgs The number of arguments.
516 * @param papszArgs The argument vector. (Note that this may be
517 * reordered, so the memory must be writable.)
518 */
519RTDECL(RTEXITCODE) RTZipUnzipCmd(unsigned cArgs, char **papszArgs);
520
521/**
522 * Helper for decompressing files of a ZIP file located in memory.
523 *
524 * @returns IPRT status code.
525 *
526 * @param ppvDst Where to store the pointer to the allocated
527 * buffer. To be freed with RTMemFree().
528 * @param pcbDst Where to store the pointer to the size of the
529 * allocated buffer.
530 * @param pvSrc Pointer to the buffer containing the .zip file.
531 * @param cbSrc Size of the buffer containing the .zip file.
532 * @param pszObject Name of the object to extract.
533 */
534RTDECL(int) RTZipPkzipMemDecompress(void **ppvDst, size_t *pcbDst, const void *pvSrc, size_t cbSrc, const char *pszObject);
535
536/**
537 * Opens a XAR filesystem stream.
538 *
539 * This is used to extract, list or check a XAR archive.
540 *
541 * @returns IPRT status code.
542 *
543 * @param hVfsIosIn The compressed input stream. The reference is
544 * not consumed, instead another one is retained.
545 * @param fFlags Flags, MBZ.
546 * @param phVfsFss Where to return the handle to the XAR filesystem
547 * stream.
548 */
549RTDECL(int) RTZipXarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
550
551/**
552 * Opens a CPIO filesystem stream.
553 *
554 * This is used to extract, list or check a CPIO archive.
555 *
556 * @returns IPRT status code.
557 *
558 * @param hVfsIosIn The input stream. The reference is not
559 * consumed, instead another one is retained.
560 * @param fFlags Flags, MBZ.
561 * @param phVfsFss Where to return the handle to the CPIO
562 * filesystem stream.
563 */
564RTDECL(int) RTZipCpioFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
565
566/** @} */
567
568RT_C_DECLS_END
569
570#endif /* !IPRT_INCLUDED_zip_h */
571
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette