VirtualBox

source: vbox/trunk/include/iprt/tar.h@ 33516

Last change on this file since 33516 was 33289, checked in by vboxsync, 14 years ago

Runtime;Main-OVF-Import: added online creation of SHA1 sums; preread/calc is done in a second worker thread; reading is cached; directly read out of an ova file; started to make reading fully streaming aware
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.0 KB
Line 
1/** @file
2 * IPRT - Tar archive I/O.
3 */
4
5/*
6 * Copyright (C) 2009-2010 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_tar_h
27#define ___iprt_tar_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/time.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_tar RTTar - Tar archive I/O
36 * @ingroup grp_rt
37 * @{
38 */
39
40/** A tar handle */
41typedef R3PTRTYPE(struct RTTARINTERNAL *) RTTAR;
42/** Pointer to a RTTAR interface handle. */
43typedef RTTAR *PRTTAR;
44/** Nil RTTAR interface handle. */
45#define NIL_RTTAR ((RTTAR)0)
46
47/** A tar file handle */
48typedef R3PTRTYPE(struct RTTARFILEINTERNAL *) RTTARFILE;
49/** Pointer to a RTTARFILE interface handle. */
50typedef RTTARFILE *PRTTARFILE;
51/** Nil RTTARFILE interface handle. */
52#define NIL_RTTARFILE ((RTTARFILE)0)
53
54/**
55 * Opens a Tar archive.
56 *
57 * Use the mask to specify the access type. In create mode the target file
58 * have not to exists.
59 *
60 * @returns IPRT status code.
61 *
62 * @param phTar Where to store the RTTAR handle.
63 * @param pszTarname The file name of the tar archive to open.
64 * @param fMode Open flags, i.e a combination of the RTFILE_O_* defines.
65 * The ACCESS, ACTION and DENY flags are mandatory!
66 * @param fStream Open the file in stream mode. Within this mode no
67 * seeking is allowed. Use this together with
68 * RTTarFileCurrent, RTTarFileOpenCurrent,
69 * RTTarFileSeekNextFile and the read method to
70 * sequential read a tar file. Currently ignored with
71 * RTFILE_O_WRITE.
72 */
73RTR3DECL(int) RTTarOpen(PRTTAR phTar, const char* pszTarname, uint32_t fMode, bool fStream);
74
75/**
76 * Close the Tar archive.
77 *
78 * @returns IPRT status code.
79 *
80 * @param hTar Handle to the RTTAR interface.
81 */
82RTR3DECL(int) RTTarClose(RTTAR hTar);
83
84/**
85 * Open a file in the Tar archive.
86 *
87 * @remark: Write mode means append mode only. It is not possible to make
88 * changes to existing files.
89 *
90 * @remark: Currently it is not possible to open more than one file in write
91 * mode. Although open more than one file in read only mode (even when one file
92 * is opened in write mode) is always possible.
93 *
94 * @returns IPRT status code.
95 *
96 * @param hTar The hande of the tar archive.
97 * @param phFile Where to store the handle to the opened file.
98 * @param pszFilename Path to the file which is to be opened. (UTF-8)
99 * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
100 * The ACCESS, ACTION flags are mandatory! DENY flags
101 * are currently not supported.
102 */
103RTR3DECL(int) RTTarFileOpen(RTTAR hTar, PRTTARFILE phFile, const char *pszFilename, uint32_t fOpen);
104
105/**
106 * Close the file opened by RTTarFileOpen.
107 *
108 * @returns IPRT status code.
109 *
110 * @param hFile The file handle to close.
111 */
112RTR3DECL(int) RTTarFileClose(RTTARFILE hFile);
113
114/**
115 * Changes the read & write position in a file.
116 *
117 * @returns IPRT status code.
118 *
119 * @param hFile Handle to the file.
120 * @param offSeek Offset to seek.
121 * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
122 * @param poffActual Where to store the new file position.
123 * NULL is allowed.
124 */
125RTR3DECL(int) RTTarFileSeek(RTTARFILE hFile, uint64_t uOffset, unsigned uMethod, uint64_t *poffActual);
126
127/**
128 * Gets the current file position.
129 *
130 * @returns File offset.
131 * @returns ~0ULL on failure.
132 *
133 * @param hFile Handle to the file.
134 */
135RTR3DECL(uint64_t) RTTarFileTell(RTTARFILE hFile);
136
137/**
138 * Read bytes from a file.
139 *
140 * @returns IPRT status code.
141 *
142 * @param hFile Handle to the file.
143 * @param pvBuf Where to put the bytes we read.
144 * @param cbToRead How much to read.
145 * @param *pcbRead How much we actually read .
146 * If NULL an error will be returned for a partial read.
147 */
148RTR3DECL(int) RTTarFileRead(RTTARFILE hFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
149
150/**
151 * Read bytes from a file at a given offset.
152 * This function may modify the file position.
153 *
154 * @returns IPRT status code.
155 *
156 * @param hFile Handle to the file.
157 * @param uOffset Where to read.
158 * @param pvBuf Where to put the bytes we read.
159 * @param cbToRead How much to read.
160 * @param *pcbRead How much we actually read .
161 * If NULL an error will be returned for a partial read.
162 */
163RTR3DECL(int) RTTarFileReadAt(RTTARFILE hFile, uint64_t uOffset, void *pvBuf, size_t cbToRead, size_t *pcbRead);
164
165/**
166 * Write bytes to a file.
167 *
168 * @returns IPRT status code.
169 *
170 * @param hFile Handle to the file.
171 * @param pvBuf What to write.
172 * @param cbToWrite How much to write.
173 * @param *pcbWritten How much we actually wrote.
174 * If NULL an error will be returned for a partial write.
175 */
176RTR3DECL(int) RTTarFileWrite(RTTARFILE hFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
177
178/**
179 * Write bytes to a file at a given offset.
180 * This function may modify the file position.
181 *
182 * @returns IPRT status code.
183 *
184 * @param hFile Handle to the file.
185 * @param uOffset Where to write.
186 * @param pvBuf What to write.
187 * @param cbToWrite How much to write.
188 * @param *pcbWritten How much we actually wrote.
189 * If NULL an error will be returned for a partial write.
190 */
191RTR3DECL(int) RTTarFileWriteAt(RTTARFILE hFile, uint64_t uOffset, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
192
193/**
194 * Query the size of the file.
195 *
196 * @returns IPRT status code.
197 *
198 * @param hFile Handle to the file.
199 * @param pcbSize Where to store the filesize.
200 */
201RTR3DECL(int) RTTarFileGetSize(RTTARFILE hFile, uint64_t *pcbSize);
202
203/**
204 * Set the size of the file.
205 *
206 * @returns IPRT status code.
207 *
208 * @param hFile Handle to the file.
209 * @param cbSize The new file size.
210 */
211RTR3DECL(int) RTTarFileSetSize(RTTARFILE hFile, uint64_t cbSize);
212
213/**
214 * Gets the mode flags of an open file.
215 *
216 * @returns IPRT status code.
217 *
218 * @param hFile Handle to the file.
219 * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
220 */
221RTR3DECL(int) RTTarFileGetMode(RTTARFILE hFile, uint32_t *pfMode);
222
223/**
224 * Changes the mode flags of an open file.
225 *
226 * @returns IPRT status code.
227 *
228 * @param hFile Handle to the file.
229 * @param fMode The new file mode, see @ref grp_rt_fs for details.
230 */
231RTR3DECL(int) RTTarFileSetMode(RTTARFILE hFile, uint32_t fMode);
232
233/**
234 * Gets the modification timestamp of the file.
235 *
236 * @returns IPRT status code.
237 *
238 * @param pFile Handle to the file.
239 * @param pTime Where to store the time.
240 */
241RTR3DECL(int) RTTarFileGetTime(RTTARFILE hFile, PRTTIMESPEC pTime);
242
243/**
244 * Sets the modification timestamp of the file.
245 *
246 * @returns IPRT status code.
247 *
248 * @param pFile Handle to the file.
249 * @param pTime The time to store.
250 */
251RTR3DECL(int) RTTarFileSetTime(RTTARFILE hFile, PRTTIMESPEC pTime);
252
253/**
254 * Gets the owner and/or group of an open file.
255 *
256 * @returns IPRT status code.
257 *
258 * @param hFile Handle to the file.
259 * @param pUid Where to store the owner user id. NULL is ok.
260 * @param pGid Where to store the group id. NULL is ok.
261 */
262RTR3DECL(int) RTTarFileGetOwner(RTTARFILE hFile, uint32_t *pUid, uint32_t *pGid);
263
264/**
265 * Changes the owner and/or group of an open file.
266 *
267 * @returns IPRT status code.
268 *
269 * @param hFile Handle to the file.
270 * @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged.
271 * @param gid The new group id. Use -1 (or ~0) to leave this unchanged.
272 */
273RTR3DECL(int) RTTarFileSetOwner(RTTARFILE hFile, uint32_t uid, uint32_t gid);
274
275/******************************************************************************
276 * Convenience Functions *
277 ******************************************************************************/
278
279/**
280 * Check if the specified file exists in the Tar archive.
281 *
282 * (The matching is case sensitive.)
283 *
284 * @note Currently only regular files are supported.
285 *
286 * @returns IPRT status code.
287 * @retval VINF_SUCCESS when the file exists in the Tar archive.
288 * @retval VERR_FILE_NOT_FOUND when the file not exists in the Tar archive.
289 *
290 * @param pszTarFile Tar file to check.
291 * @param pszFile Filename to check for.
292 */
293RTR3DECL(int) RTTarFileExists(const char *pszTarFile, const char *pszFile);
294
295/**
296 * Create a file list from a Tar archive.
297 *
298 * @note Currently only regular files are supported.
299 *
300 * @returns IPRT status code.
301 *
302 * @param pszTarFile Tar file to list files from.
303 * @param ppapszFiles On success an array with array with the filenames is
304 * returned. The names must be freed with RTStrFree and
305 * the array with RTMemFree.
306 * @param pcFiles On success the number of entries in ppapszFiles.
307 */
308RTR3DECL(int) RTTarList(const char *pszTarFile, char ***ppapszFiles, size_t *pcFiles);
309
310/**
311 * Extract a file from a Tar archive into a memory buffer.
312 *
313 * The caller is responsible for the deletion of the returned memory buffer.
314 *
315 * (The matching is case sensitive.)
316 *
317 * @note Currently only regular files are supported. Also some of the header
318 * fields are not used (uid, gid, uname, gname, mtime).
319 *
320 * @returns IPRT status code.
321 *
322 * @param pszTarFile Tar file to extract files from.
323 * @param ppBuf The buffer which will held the extracted data.
324 * @param pcbSize The size (in bytes) of ppBuf after successful
325 * extraction.
326 * @param pszFile The file to extract.
327 * @param pfnProgressCallback Progress callback function. Optional.
328 * @param pvUser User defined data for the progress
329 * callback. Optional.
330 */
331RTR3DECL(int) RTTarExtractFileToBuf(const char *pszTarFile, void **ppvBuf, size_t *pcbSize, const char *pszFile, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
332
333/**
334 * Extract a set of files from a Tar archive.
335 *
336 * Also note that this function is atomic. If an error occurs all previously
337 * extracted files will be deleted.
338 *
339 * (The matching is case sensitive.)
340 *
341 * @note Currently only regular files are supported. Also some of the header
342 * fields are not used (uid, gid, uname, gname, mtime).
343 *
344 * @returns IPRT status code.
345 *
346 * @param pszTarFile Tar file to extract files from.
347 * @param pszOutputDir Where to store the extracted files. Must exist.
348 * @param papszFiles Which files should be extracted.
349 * @param cFiles The number of files in papszFiles.
350 * @param pfnProgressCallback Progress callback function. Optional.
351 * @param pvUser User defined data for the progress
352 * callback. Optional.
353 */
354RTR3DECL(int) RTTarExtractFiles(const char *pszTarFile, const char *pszOutputDir, const char * const *papszFiles, size_t cFiles, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
355
356/**
357 * Extract all files of the archive.
358 *
359 * @note Currently only regular files are supported. Also some of the header
360 * fields are not used (uid, gid, uname, gname, mtime).
361 *
362 * @returns IPRT status code.
363 *
364 * @param pszTarFile Tar file to extract the files from.
365 * @param pszOutputDir Where to store the extracted files. Must exist.
366 * @param pfnProgressCallback Progress callback function. Optional.
367 * @param pvUser User defined data for the progress
368 * callback. Optional.
369 */
370RTR3DECL(int) RTTarExtractAll(const char *pszTarFile, const char *pszOutputDir, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
371
372/**
373 * Create a Tar archive out of the given files.
374 *
375 * @note Currently only regular files are supported.
376 *
377 * @returns IPRT status code.
378 *
379 * @param pszTarFile Where to create the Tar archive.
380 * @param papszFiles Which files should be included.
381 * @param cFiles The number of files in papszFiles.
382 * @param pfnProgressCallback Progress callback function. Optional.
383 * @param pvUser User defined data for the progress
384 * callback. Optional.
385 */
386RTR3DECL(int) RTTarCreate(const char *pszTarFile, const char * const *papszFiles, size_t cFiles, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
387
388/******************************************************************************
389 * Streaming Functions *
390 ******************************************************************************/
391
392/**
393 * Return the filename where RTTar currently stays at.
394 *
395 * @returns IPRT status code.
396 *
397 * @param hTar Handle to the RTTAR interface.
398 * @param ppszFilename On success the filename.
399 */
400RTR3DECL(int) RTTarCurrentFile(RTTAR hTar, char **ppszFilename);
401
402/**
403 * Jumps to the next file from the current RTTar position.
404 *
405 * @returns IPRT status code.
406 *
407 * @param hTar Handle to the RTTAR interface.
408 */
409RTR3DECL(int) RTTarSeekNextFile(RTTAR hTar);
410
411/**
412 * Opens the file where RTTar currently stays at.
413 *
414 * @returns IPRT status code.
415 *
416 * @param hTar Handle to the RTTAR interface.
417 * @param phFile Where to store the handle to the opened file.
418 * @param ppszFilename On success the filename.
419 * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
420 * The ACCESS, ACTION flags are mandatory! Currently
421 * only RTFILE_O_OPEN | RTFILE_O_READ is supported.
422 */
423RTR3DECL(int) RTTarFileOpenCurrentFile(RTTAR hTar, PRTTARFILE phFile, char **ppszFilename, uint32_t fOpen);
424
425
426/** @} */
427
428RT_C_DECLS_END
429
430#endif /* ___iprt_tar_h */
431
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