minitar

Tiny and easy-to-use C library to parse tar (specifically, the newer USTAR variant, which is the one pretty much everybody uses) archives.

No third-party dependencies, only a minimally capable standard C library (pretty much only requires a basic subset of the C FILE API, apart from other simple functions).

Aims to be bloat-free (currently just above 500 LoC), fast and optimized, and as portable between systems as possible (has its own implementation of some non-standard functions, such as strlcpy or basename).

Does not include support for compressed archives. You'll have to pass those through another program or library to decompress them before minitar can handle them.

Example

#include <stdio.h>
#include <minitar.h>

int main(int argc, char** argv)
{
	if(argc == 1)
	{
		fprintf(stderr, "Usage: %s [file]\n", argv[0]);
		return 1;
	}
	struct minitar mp;
	if(minitar_open(argv[1], &mp) != 0)
	{
		perror(argv[1]);
		return 1;
	}
	struct minitar_entry entry;
	do {
		if(minitar_read_entry(&mp, &entry) == 0) { 
			printf("%s\n", entry.metadata.path);
		} else break;
	} while(1);
	minitar_close(&mp);
}

The output of this example program when running it with an uncompressed tar archive is identical to that of tar --list -f archive.tar with the same uncompressed archive. And in most cases, it's faster as well!

See examples for more examples using minitar.

Project structure

The user-facing API (functions defined in minitar.h and documented in this README) is implemented in src/tar.c. Utility and internally-used functions live in src/util.c.

Documentation

See the build instructions to start using minitar.

See the API documentation for a full description of all functions and types.

Error handling

When a fatal error occurs, minitar calls the function minitar_handle_panic() with a message describing the error. The default implementation of this function prints the error message out to standard error and aborts.

You might want to handle errors differently. Well, you can override the panic function! Just create a function with the following signature:

noreturn void minitar_handle_panic(const char* message)

and put your error handling code in there. This function will automatically override the default one used by minitar.

This function needs to have C linkage and be unmangled. If you're using other languages, this might not be the case, for example, a C++ implementation would need the following signature:

extern "C" [[noreturn]] void minitar_handle_panic(const char* message)

and a Rust implementation would need:

#[no_mangle]
pub extern "C" fn minitar_handle_panic(message: *const u8) -> !

License

minitar is free and open-source software under the BSD-2-Clause license.