VirtualBox

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

Last change on this file since 76557 was 76557, checked in by vboxsync, 6 years ago

include/iprt: Use IPRT_INCLUDED_ rather than _iprt_ as header guard prefix, letting scm enforce this (thereby avoiding copy&paste errors like rsa.h).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.6 KB
Line 
1/** @file
2 * IPRT - Tar archive I/O.
3 */
4
5/*
6 * Copyright (C) 2009-2019 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_INCLUDED_tar_h
27#define IPRT_INCLUDED_tar_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34#include <iprt/time.h>
35
36RT_C_DECLS_BEGIN
37
38/** @defgroup grp_rt_tar RTTar - Tar archive I/O
39 * @ingroup grp_rt
40 *
41 * @deprecated Only used for legacy code and writing. Migrate new code to the
42 * VFS interface, add the write part when needed.
43 *
44 * @{
45 */
46
47/** A tar handle */
48typedef R3PTRTYPE(struct RTTARINTERNAL *) RTTAR;
49/** Pointer to a RTTAR interface handle. */
50typedef RTTAR *PRTTAR;
51/** Nil RTTAR interface handle. */
52#define NIL_RTTAR ((RTTAR)0)
53
54/** A tar file handle */
55typedef R3PTRTYPE(struct RTTARFILEINTERNAL *) RTTARFILE;
56/** Pointer to a RTTARFILE interface handle. */
57typedef RTTARFILE *PRTTARFILE;
58/** Nil RTTARFILE interface handle. */
59#define NIL_RTTARFILE ((RTTARFILE)0)
60
61/** Maximum length of a tar filename, excluding the terminating '\0'. More
62 * does not fit into a tar record. */
63#define RTTAR_NAME_MAX 99
64
65/**
66 * Creates a Tar archive.
67 *
68 * Use the mask to specify the access type.
69 *
70 * @returns IPRT status code.
71 *
72 * @param phTar Where to store the RTTAR handle.
73 * @param pszTarname The file name of the tar archive to create. Should
74 * not exist.
75 * @param fMode Open flags, i.e a combination of the RTFILE_O_* defines.
76 * The ACCESS, ACTION and DENY flags are mandatory!
77 */
78RTR3DECL(int) RTTarOpen(PRTTAR phTar, const char *pszTarname, uint32_t fMode);
79
80/**
81 * Close the Tar archive.
82 *
83 * @returns IPRT status code.
84 *
85 * @param hTar Handle to the RTTAR interface.
86 */
87RTR3DECL(int) RTTarClose(RTTAR hTar);
88
89/**
90 * Open a file in the Tar archive.
91 *
92 * @returns IPRT status code.
93 *
94 * @param hTar The handle of the tar archive.
95 * @param phFile Where to store the handle to the opened file.
96 * @param pszFilename Path to the file which is to be opened. (UTF-8)
97 * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
98 * The ACCESS, ACTION flags are mandatory! DENY flags
99 * are currently not supported.
100 *
101 * @remarks Write mode means append mode only. It is not possible to make
102 * changes to existing files.
103 *
104 * @remarks Currently it is not possible to open more than one file in write
105 * mode. Although open more than one file in read only mode (even when
106 * one file is opened in write mode) is always possible.
107 */
108RTR3DECL(int) RTTarFileOpen(RTTAR hTar, PRTTARFILE phFile, const char *pszFilename, uint32_t fOpen);
109
110/**
111 * Close the file opened by RTTarFileOpen.
112 *
113 * @returns IPRT status code.
114 *
115 * @param hFile The file handle to close.
116 */
117RTR3DECL(int) RTTarFileClose(RTTARFILE hFile);
118
119/**
120 * Read bytes from a file at a given offset.
121 * This function may modify the file position.
122 *
123 * @returns IPRT status code.
124 *
125 * @param hFile Handle to the file.
126 * @param off Where to read.
127 * @param pvBuf Where to put the bytes we read.
128 * @param cbToRead How much to read.
129 * @param pcbRead Where to return how much we actually read. If NULL
130 * an error will be returned for a partial read.
131 */
132RTR3DECL(int) RTTarFileReadAt(RTTARFILE hFile, uint64_t off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
133
134/**
135 * Write bytes to a file at a given offset.
136 * This function may modify the file position.
137 *
138 * @returns IPRT status code.
139 *
140 * @param hFile Handle to the file.
141 * @param off Where to write.
142 * @param pvBuf What to write.
143 * @param cbToWrite How much to write.
144 * @param pcbWritten Where to return how much we actually wrote. If NULL
145 * an error will be returned for a partial write.
146 */
147RTR3DECL(int) RTTarFileWriteAt(RTTARFILE hFile, uint64_t off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
148
149/**
150 * Query the size of the file.
151 *
152 * @returns IPRT status code.
153 *
154 * @param hFile Handle to the file.
155 * @param pcbSize Where to store the filesize.
156 */
157RTR3DECL(int) RTTarFileGetSize(RTTARFILE hFile, uint64_t *pcbSize);
158
159/**
160 * Set the size of the file.
161 *
162 * @returns IPRT status code.
163 *
164 * @param hFile Handle to the file.
165 * @param cbSize The new file size.
166 */
167RTR3DECL(int) RTTarFileSetSize(RTTARFILE hFile, uint64_t cbSize);
168
169/** @} */
170
171RT_C_DECLS_END
172
173#endif
174
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