Recursive AI

Create a cpio archive in C#

OneArchive is a free, open-source archive and compression library for .NET from Recursive AI: archives (zip, tar, 7z, RAR 5, cpio, ar, ISO) in RecursiveAI.OneArchive, codecs (zlib, gzip, xz, Zstandard, Brotli) in RecursiveAI.OneCompress. MIT or Apache-2.0, no native dependencies.

A cpio archive packs files and their paths into one container. The default writer creates the newc format.

Terminal
dotnet add package RecursiveAI.OneArchive

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneArchive;
using RecursiveAI.OneArchive.Cpio;
 
using var output = File.Create("files.cpio");
using var writer = new CpioWriter(output);
writer.WriteEntry(
    new ArchiveEntry
    { Name = "docs/hello.txt", Size = 15 },
    "Hello archive!\n"u8.ToArray());
writer.Finish();
Console.WriteLine("Wrote files.cpio");
Text
Wrote files.cpio

Unzip the example, then dotnet run.

The full program

The input is generated in code: Hello archive! followed by a newline. The full program writes files.cpio, reopens it and compares the stored text.

C#
using RecursiveAI.OneArchive;
using RecursiveAI.OneArchive.Cpio;
 
using (var output = File.Create("files.cpio"))
using (var writer = new CpioWriter(output))
{
    writer.WriteEntry(
        new ArchiveEntry { Name = "docs/hello.txt", Size = 15 },
        "Hello archive!\n"u8.ToArray());
    writer.Finish();
}
Console.WriteLine("Wrote files.cpio");
using var input = File.OpenRead("files.cpio");
using var reader = new CpioReader(input);
while (reader.GetNextEntry() is { } entry)
{
    using var content = new StreamReader(reader.OpenEntryStream());
    string text = content.ReadToEnd();
    if (text != "Hello archive!\n")
        throw new InvalidDataException("Content changed");
    Console.WriteLine($"{entry.Name}: {entry.Size} bytes");
    Console.Write(text);
}

dotnet run prints:

Text
Wrote files.cpio
docs/hello.txt: 15 bytes
Hello archive!

A header field that does not fit the selected format raises ArchiveUnsupportedException naming the field and entry.

Variations

Use the CRC variant to add a byte-sum checksum to regular-file data. This replaces the snippet at the top.

C#
using RecursiveAI.OneArchive;
using RecursiveAI.OneArchive.Cpio;
 
using var output = File.Create("files.cpio");
using var writer = new CpioWriter(output,
    new() { Format = CpioFormat.Crc });
writer.WriteEntry(
    new ArchiveEntry { Name = "docs/hello.txt", Size = 15 },
    "Hello archive!\n"u8.ToArray());
writer.Finish();
Console.WriteLine("Wrote files.cpio");
Text
Wrote files.cpio

Read a real file from disk instead. hello.txt comes in the download and contains Hello archive! followed by a newline. Size must equal the content’s byte length; content.Length computes it here.

C#
using RecursiveAI.OneArchive;
using RecursiveAI.OneArchive.Cpio;
 
byte[] content = File.ReadAllBytes("hello.txt");
using var output = File.Create("from-disk.cpio");
using var writer = new CpioWriter(output);
writer.WriteEntry(new ArchiveEntry
{
    Name = "hello.txt", Size = content.Length
}, content);
writer.Finish();
Console.WriteLine($"Archived {content.Length} bytes");
Text
Archived 15 bytes

The short answer

Use CpioWriter from RecursiveAI.OneArchive, give each member its archive path and byte size, then call Finish. The default format is newc, the new ASCII header format. The full example writes a generated text member, closes the writer and reads the bytes back with CpioReader.

The archive is not compressed. Choosing CRC changes the cpio header and adds a data checksum; it does not select a compression algorithm. The cpio format documentation describes the three supported header variants and the writer’s metadata defaults.

How do I create a cpio archive in C#?

The snippet at the top creates a file, wraps it in CpioWriter, and writes the content from a UTF-8 byte literal. It needs no source directory or shell command. For each member, ArchiveEntry.Name is the stored path and Size is the content length in bytes. A path does not instruct this API to find and load a file: the content argument supplies the bytes.

Choose the format according to the consuming program’s requirements. Newc is the default. CRC uses the newc layout with a byte-sum checksum for regular files. Odc is the older portable ASCII layout, with different field widths. Old binary cpio is recognized by the reader but raises ArchiveUnsupportedException; it is not an output choice.

Call Finish before consuming the output. It writes the TRAILER!!! entry and the final padding; the default output block size is 512 bytes. The trailer is a format marker, not another application file. The reader requires it by default, so a stream ending at a member boundary without the trailer is still truncated.

How do I create a cpio archive with a custom structure?

Set the stored name independently of the source location. In this example, docs/hello.txt becomes a path inside the archive even though the program creates its content in memory. The program does not create a local docs folder. Reopening the container and printing that name shows what was stored without extracting anything onto disk.

For a directory entry, set Kind = ArchiveEntryKind.Directory rather than relying on a trailing slash. After creating a CpioWriter named writer, add the directory with:

C#
writer.WriteEntry(new ArchiveEntry {
    Name = "docs", Kind = ArchiveEntryKind.Directory
});

The writer drops a directory’s trailing slash. Files default to permissions 0644, directories to 0755, and symbolic links to 0777; missing owner and group IDs are zero, and missing modification time is zero. These are stored values, not a snapshot of the host process’s permissions or clock.

Hard links need special handling. A generic hard-link entry is refused because the streaming writer cannot know which name will carry the shared data. The documented cpio-specific route uses CpioEntry values with matching inode and link counts, empty content for earlier names, and the content on the last name.

For CRC output, the checksum must precede the content. A seekable content stream is read twice. Non-seekable content is buffered up to MaxBufferedSize, whose default is 64 MiB, and larger content is refused. Reading each regular file from start to end verifies its checksum by default; merely skipping over an entry does not.

All onearchive recipes