Tar C Library Reference

Tar

API for creating and extracting TAR archives. Also supports creating and extracting .tar.gz (.tgz), .tar.bz2, and .tar.Z (compressed TAR archives, also known as compressed tarball archives). Can read/write the following TAR formats: (1) GNU tar 1.13.x format, (2) PAX -- POSIX 1003.1-2001 format, (3) USTAR -- POSIX 1003.1-1988 format.

Create/Dispose

HCkTar CkTar_Create(void);

Creates an instance of the CkTar object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkTar_Dispose(HCkTar handle);

Objects created by calling CkTar_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

C "Properties"

void CkTar_getCharset(HCkTar cHandle, HCkString retval);
void CkTar_putCharset(HCkTar cHandle, const char *newVal);

Character encoding to be used when interpreting filenames within .tar archives for untar operations. The default is "utf-8", and this is typically not changed. (The WriteTar methods always uses utf-8 to store filenames within the TAR archive.)

int CkTar_getDirMode(HCkTar cHandle);
void CkTar_putDirMode(HCkTar cHandle, int newVal);

The directory permissions to used in WriteTar* methods. The default is octal 0755. This is the value to be stored in the "mode" field of each TAR header for a directory entries.

void CkTar_getDirPrefix(HCkTar cHandle, HCkString retval);
void CkTar_putDirPrefix(HCkTar cHandle, const char *newVal);

To be documented soon...

int CkTar_getFileMode(HCkTar cHandle);
void CkTar_putFileMode(HCkTar cHandle, int newVal);

The file permissions to used in WriteTar* methods. The default is octal 0644. This is the value to be stored in the "mode" field of each TAR header for a file entries.

int CkTar_getGroupId(HCkTar cHandle);
void CkTar_putGroupId(HCkTar cHandle, int newVal);

The default numerical GID to be stored in each TAR header when writing TAR archives. The default value is 1000.

void CkTar_getGroupName(HCkTar cHandle, HCkString retval);
void CkTar_putGroupName(HCkTar cHandle, const char *newVal);

The default group name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process.

int CkTar_getHeartbeatMs(HCkTar cHandle);
void CkTar_putHeartbeatMs(HCkTar cHandle, int newVal);

This is the number of milliseconds between each AbortCheck event callback. The AbortCheck callback allows an application to abort any TAR operation prior to completion. If HeartbeatMs is 0, no AbortCheck event callbacks will occur.

void CkTar_getLastErrorHtml(HCkTar cHandle, HCkString retval);

Error information in HTML format for the last method called.

void CkTar_getLastErrorText(HCkTar cHandle, HCkString retval);

To be documented soon.Error information in plain-text format for the last method called.

void CkTar_getLastErrorXml(HCkTar cHandle, HCkString retval);

To be documented soon.Error information in XML format for the last method called.

BOOL CkTar_getNoAbsolutePaths(HCkTar cHandle);
void CkTar_putNoAbsolutePaths(HCkTar cHandle, BOOL newVal);

If true, then absolute paths are converted to relative paths by removing the leading "/" or "\" character when untarring. This protects your system from unknowingly untarring files into important system directories, such as C:\Windows\system32. The default value is true.

int CkTar_getNumDirRoots(HCkTar cHandle);

The total number of directory roots set by calling AddDirRoot (i.e. the number of times AddDirRoot was called by the application). A TAR archive is created by calling AddDirRoot for one or more directory tree roots, followed by a single call to WriteTar (or WriteTarBz2, WriteTarGz, WriteTarZ). This allows for TAR archives containing multiple directory trees to be created.

int CkTar_getScriptFileMode(HCkTar cHandle);
void CkTar_putScriptFileMode(HCkTar cHandle, int newVal);

The file permissions to used in WriteTar* methods for shell script files (.sh, .csh, .bash, .bsh). The default is octal 0755. This is the value to be stored in the "mode" field of each TAR header for a file entries.

BOOL CkTar_getUntarCaseSensitive(HCkTar cHandle);
void CkTar_putUntarCaseSensitive(HCkTar cHandle, BOOL newVal);

Determines whether pattern matching is case-sensitive if the UntarMatchPattern is used. The default value is false.

BOOL CkTar_getUntarDebugLog(HCkTar cHandle);
void CkTar_putUntarDebugLog(HCkTar cHandle, BOOL newVal);

Similar to the VerboseLogging property. If set to true, then information about each file/directory extracted in an untar method call is logged to LastErrorText (or LastErrorXml / LastErrorHtml). The default value is false.

BOOL CkTar_getUntarDiscardPaths(HCkTar cHandle);
void CkTar_putUntarDiscardPaths(HCkTar cHandle, BOOL newVal);

If true, then discard all path information when untarring. This causes all files to be untarred into a single directory. The default value is false.

void CkTar_getUntarFromDir(HCkTar cHandle, HCkString retval);
void CkTar_putUntarFromDir(HCkTar cHandle, const char *newVal);

The directory path where files are extracted when untarring. The default value is ".", meaning that the current working directory of the calling process is used. If UntarDiscardPaths is set, then all files are untarred into this directory. Otherwise, the untar operation will re-create a directory tree rooted in this directory.

void CkTar_getUntarMatchPattern(HCkTar cHandle, HCkString retval);
void CkTar_putUntarMatchPattern(HCkTar cHandle, const char *newVal);

Used to untar only files and directories that match this pattern. The asterisk character represents 0 or more of any character. For example, setting this pattern to "*.txt" causes all .txt files to be extracted. The default value is an empty string, indicating that all files are to be extracted.

int CkTar_getUntarMaxCount(HCkTar cHandle);
void CkTar_putUntarMaxCount(HCkTar cHandle, int newVal);

Limits the number of files extracted during an untar to this count. The default value is 0 to indicate no maximum. To untar a single file, one might set the UntarMatchPattern such that it will match only the file to be extracted, and also set UntarMaxCount equal to 1. This causes an untar to scan the TAR archive until it finds the matching file, extract it, and then return.

int CkTar_getUserId(HCkTar cHandle);
void CkTar_putUserId(HCkTar cHandle, int newVal);

The default numerical UID to be stored in each TAR header when writing TAR archives. The default value is 1000.

void CkTar_getUserName(HCkTar cHandle, HCkString retval);
void CkTar_putUserName(HCkTar cHandle, const char *newVal);

The default user name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process.

BOOL CkTar_getUtf8(HCkTar cHandle);
void CkTar_putUtf8(HCkTar cHandle, BOOL newVal);

To be documented soon...

BOOL CkTar_getVerboseLogging(HCkTar cHandle);
void CkTar_putVerboseLogging(HCkTar cHandle, BOOL newVal);

If set to true, then the LastErrorText may contain more verbose logging.

void CkTar_getVersion(HCkTar cHandle, HCkString retval);

The version of the TAR component/library, such as 1.0.0.

void CkTar_getWriteFormat(HCkTar cHandle, HCkString retval);
void CkTar_putWriteFormat(HCkTar cHandle, const char *newVal);

The TAR format to use when writing a TAR archive. Valid values are "gnu", "pax", and "ustar". The default value is "gnu".

C "Methods"

BOOL CkTar_AddDirRoot(HCkTar cHandle, const char *dirPath);

Adds a directory tree to be included in the next call to one of the WriteTar* methods. To include multiple directory trees in a .tar, call AddDirRoot multiple times followed by a single call to WriteTar.

Returns TRUE for success, FALSE for failure.

BOOL CkTar_GetDirRoot(HCkTar cHandle, int index, HCkString outStr);

Returns the value of the Nth directory root. For example, if an application calls AddDirRoot twice, then the NumDirRoots property would have a value of 2, and GetDirRoot(0) would return the path passed to AddDirRoot in the 1st call, and GetDirRoot(1) would return the directory path in the 2nd call to AddDirRoot.

BOOL CkTar_ListXml(HCkTar cHandle, const char *tarFilename, HCkString outStr);

Scans a TAR archive and returns XML detailing the files and directories found within the TAR.

BOOL CkTar_SaveLastError(HCkTar cHandle, const char *filename);

Saves the last error information to an XML formatted file.

BOOL CkTar_UnlockComponent(HCkTar cHandle, const char *unlockCode);

Unlocks the component allowing for the full functionality to be used. If this method unexpectedly returns false, examine the contents of the LastErrorText property to determine the reason for failure.

int CkTar_Untar(HCkTar cHandle, const char *tarFilename);

Extracts the files and directories from a TAR archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns the number of files and directories extracted, or -1 for failure.

BOOL CkTar_UntarBz2(HCkTar cHandle, const char *tarFilename);

Extracts the files and directories from a tar.bz2 (or tar.bzip2) archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property.

Returns TRUE for success, FALSE for failure.

BOOL CkTar_UntarFirstMatchingToMemory(HCkTar cHandle, HCkByteData tarFileBytes, const char *matchPattern, HCkByteData outBytes);

Memory-to-memory untar. The first file matching the UntarMatchPattern property is extracted and returned.

int CkTar_UntarFromMemory(HCkTar cHandle, HCkByteData tarFileBytes);

Extracts the files and directories from an in-memory TAR archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns the number of files and directories extracted, or -1 for failure.

BOOL CkTar_UntarGz(HCkTar cHandle, const char *tarFilename);

Extracts the files and directories from a tar.gz (or tar.gzip) archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property.

Returns TRUE for success, FALSE for failure.

BOOL CkTar_UntarZ(HCkTar cHandle, const char *tarFilename);

Extracts the files and directories from a tar.Z archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property.

Returns TRUE for success, FALSE for failure.

BOOL CkTar_VerifyTar(HCkTar cHandle, const char *tarFilename);

To be documented soon...

BOOL CkTar_WriteTar(HCkTar cHandle, const char *tarFilename);

Writes a TAR archive. The directory trees previously added by calling AddDirRoot one or more times are included in the output TAR archive.

Returns TRUE for success, FALSE for failure.

BOOL CkTar_WriteTarBz2(HCkTar cHandle, const char *outFilename);

Writes a .tar.bz2 compressed TAR archive. The directory trees previously added by calling AddDirRoot one or more times are included in the output file.

Returns TRUE for success, FALSE for failure.

BOOL CkTar_WriteTarGz(HCkTar cHandle, const char *outFilename);

Writes a .tar.gz (also known as .tgz) compressed TAR archive. The directory trees previously added by calling AddDirRoot one or more times are included in the output file.

Returns TRUE for success, FALSE for failure.

const char *CkTar_charset(HCkTar cHandle);

Character encoding to be used when interpreting filenames within .tar archives for untar operations. The default is "utf-8", and this is typically not changed. (The WriteTar methods always uses utf-8 to store filenames within the TAR archive.)

Returns a null on failure

const char *CkTar_dirPrefix(HCkTar cHandle);

To be documented soon...

const char *CkTar_getDirRoot(HCkTar cHandle, int index);

Returns the value of the Nth directory root. For example, if an application calls AddDirRoot twice, then the NumDirRoots property would have a value of 2, and GetDirRoot(0) would return the path passed to AddDirRoot in the 1st call, and GetDirRoot(1) would return the directory path in the 2nd call to AddDirRoot.

Returns a null on failure

const char *CkTar_groupName(HCkTar cHandle);

The default group name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process.

Returns a null on failure

const char *CkTar_lastErrorHtml(HCkTar cHandle);

Error information in HTML format for the last method called.

Returns a null on failure

const char *CkTar_lastErrorText(HCkTar cHandle);

Error information in plain-text format for the last method called.

Returns a null on failure

const char *CkTar_lastErrorXml(HCkTar cHandle);

Error information in XML format for the last method called.

Returns a null on failure

const char *CkTar_listXml(HCkTar cHandle, const char *tarFilename);

Scans a TAR archive and returns XML detailing the files and directories found within the TAR.

Returns a null on failure

const char *CkTar_untarFromDir(HCkTar cHandle);

The directory path where files are extracted when untarring. The default value is ".", meaning that the current working directory of the calling process is used. If UntarDiscardPaths is set, then all files are untarred into this directory. Otherwise, the untar operation will re-create a directory tree rooted in this directory.

Returns a null on failure

const char *CkTar_untarMatchPattern(HCkTar cHandle);

Used to untar only files and directories that match this pattern. The asterisk character represents 0 or more of any character. For example, setting this pattern to "*.txt" causes all .txt files to be extracted. The default value is an empty string, indicating that all files are to be extracted.

Returns a null on failure

const char *CkTar_userName(HCkTar cHandle);

The default user name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process.

Returns a null on failure

const char *CkTar_version(HCkTar cHandle);

The version of the TAR component/library, such as 1.0.0.

Returns a null on failure

const char *CkTar_writeFormat(HCkTar cHandle);

The TAR format to use when writing a TAR archive. Valid values are "gnu", "pax", and "ustar". The default value is "gnu".

Returns a null on failure