zip.h@ 104956

Last change on this file since 104956 was 98732, checked in by vboxsync, 21 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
45	RT_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	*/
62	typedef DECLCALLBACKTYPE(int, FNRTZIPOUT,(void pvUser, const void pvBuf, size_t cbBuf));
63	/** Pointer to FNRTZIPOUT() function. */
64	typedef 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	*/
75	typedef DECLCALLBACKTYPE(int, FNRTZIPIN,(void pvUser, void pvBuf, size_t cbBuf, size_t *pcbBuf));
76	/** Pointer to FNRTZIPIN() function. */
77	typedef FNRTZIPIN *PFNRTZIPIN;
78
79	/**
80	* Compression type.
81	* (Be careful with these they are stored in files!)
82	*/
83	typedef 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	*/
110	typedef 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	*/
133	RTDECL(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	*/
143	RTDECL(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	*/
152	RTDECL(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	*/
160	RTDECL(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	*/
171	RTDECL(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	*/
184	RTDECL(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	*/
192	RTDECL(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	*/
209	RTDECL(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	*/
228	RTDECL(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	*/
245	RTDECL(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	*/
266	RTDECL(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	*/
282	RTDECL(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	*/
298	RTDECL(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	*/
310	RTDECL(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	*/
325	RTDECL(int) RTZipTarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
326
327	/** TAR format type. */
328	typedef 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	*/
365	RTDECL(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	*/
395	RTDECL(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	*/
407	RTDECL(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	*/
419	RTDECL(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	*/
429	RTDECL(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	*/
439	RTDECL(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	*/
449	RTDECL(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	*/
459	RTDECL(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	*/
482	RTDECL(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	*/
493	RTDECL(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	*/
508	RTDECL(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	*/
519	RTDECL(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	*/
534	RTDECL(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	*/
549	RTDECL(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	*/
564	RTDECL(int) RTZipCpioFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
565
566	/** @} */
567
568	RT_C_DECLS_END
569
570	#endif /* !IPRT_INCLUDED_zip_h */
571

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: