kTar Class Reference

Description

Class to create and extract tar archives.

kTar class can be used to create or extract tar archives.

There are several tar formats. This class supports the ustar (IEEE Std 1003.1-1988) and the pax format (IEEE Std 1003.1-2001). It always uses the pax format when creating archives.

The class provides some convenient functions to archive a file or directory and to extract a stream or a file. To gain finer control, kTar_BeginWrite and kTar_BeginRead can be used for creating an archive or extracting an archive, respectively.

The following example illustrates the extraction of a tar file using kTar_BeginRead and streaming operations.

kStatus ReadTarFile(kStream stream)
{
    kTar tar = kNULL;
    kChar name[kPATH_MAX];
    kBool isDirectory;
    k64u itemSize;
    kByte b;

    kCheck(kTar_Construct(&tar, stream, kTAR_MODE_READ, kNULL));

    while (kSuccess(kTar_BeginRead(tar, name, kCountOf(name), &isDirectory, &itemSize)))
    {
        kLogf("%s: %s, size = %llu", name, isDirectory ? "directory" : "file", itemSize);

        for (kSize i = 0; i < itemSize; i++)
        {
            kCheck(kStream_Read(tar, &b, 1));
        }
    }

    return kOK;
}

The following example illustrates how to create a tar file using kTar_BeginWrite and streaming operations.

kStatus Archive()
{
    kFile outFile = kNULL;
    kChar fileName[kPATH_MAX];
    kTar tar = kNULL;
    const kSize itemSize = 100;
    const kChar buffer[itemSize] = { 'b' };

    kTry
    {
        kTest(kStrCopy(fileName, kCountOf(fileName), "archive.tar"));

        kTest(kFile_Construct(&outFile, fileName, kFILE_MODE_WRITE, kNULL));
        kTest(kFile_SetWriteBuffer(outFile, 64 * 1024));

        kTest(kTar_Construct(&tar, outFile, kTAR_MODE_WRITE, kNULL));

        kTest(kTar_BeginWrite(tar, "1", kTRUE, 0));
        kTest(kTar_BeginWrite(tar, "1/2", kTRUE, 0));

        kTest(kTar_BeginWrite(tar, "3/4/file", kFALSE, itemSize));

        kTest(kStream_Write(tar, buffer, itemSize));
    }
    kFinally
    {
        kCheck(kObject_Destroy(tar));
        kCheck(kObject_Destroy(outFile));

        kEndFinally();
    }

    return kOK;
}

Inheritance diagram for kTar:

Public Member Functions
kStatus	kTar_Archive (const kChar *sourcePath, kStream destStream)
	Archives a file or directory to a destination stream. More...
kStatus	kTar_Archive (const kChar *sourcePath, const kChar *destFilePath)
	Archives a file or directory to a file. More...
kStatus	kTar_BeginRead (kTar tar, kChar *itemPath, kSize itemPathCapacity, kBool *isDirectory, k64u *fileSize)
	Seeks to the next item in a kTar object opened in read mode. More...
kStatus	kTar_BeginWrite (kTar tar, const kChar *itemPath, kBool isDirectory, k64u itemSize)
	Prepares a kTar object opened in write mode for the next item. More...
kStatus	kTar_Close (kTar tar)
	Closes a tar stream opened in write mode. More...
kStatus	kTar_Construct (kTar *tar, kStream stream, kTarMode mode, kAlloc allocator)
	Constructs a kTar object. More...
kStatus	kTar_Extract (kStream source, const kChar *destParent)
	Extracts a tar archive from a stream to a destination path. More...
kStatus	kTar_Extract (const kChar *sourcePath, const kChar *destParent)
	Extracts a tar archive from a file path to a destination path. More...
kStatus	kTar_Find (kTar tar, const kChar *itemPath, kBool *isDirectory, k64u *fileSize)
	Convenience method to find a file or directory in an archive. More...
kStatus	kTar_ReadFile (kTar tar, const kChar *filePath, k64u fileSize)
	Convenience method to read a file from an archive and save it to a file system path. More...
kStatus	kTar_WriteDirectory (kTar tar, const kChar *itemPath)
	Adds a directory entry to an archive. More...
kStatus	kTar_WriteDirectory (kTar tar, const kChar *itemPath, const kChar *directoryPath)
	Recursively adds a directory and its contents to an archive. More...
kStatus	kTar_WriteFile (kTar tar, const kChar *itemPath, kStream stream, k64u fileSize)
	Adds a file to the tar archive by reading the file contents from a source stream. More...
kStatus	kTar_WriteFile (kTar tar, const kChar *itemPath, const kChar *filePath)
	Adds a file to the tar archive by reading the file contents from a source file. More...

---

The documentation for this class was generated from the following file:

• Utils/kTar.h