72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# minitar
|
|
|
|
Tiny C library to interact with tar archives
|
|
|
|
## 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 = minitar_open(argv[1]);
|
|
if(!mp)
|
|
{
|
|
perror(argv[1]);
|
|
return 1;
|
|
}
|
|
struct minitar_entry* entry;
|
|
do {
|
|
entry = minitar_read_entry(mp);
|
|
if(entry) {
|
|
printf("Found file %s\n", entry->metadata.name);
|
|
minitar_free_entry(entry);
|
|
}
|
|
} while(entry);
|
|
minitar_close(mp);
|
|
}
|
|
```
|
|
|
|
This program will list out the files in a tar archive :)
|
|
|
|
## API
|
|
### minitar_open
|
|
`struct minitar* minitar_open(const char* filename)`
|
|
|
|
Opens a tar archive for reading, and returns a heap-allocated `struct minitar` which must be freed with `minitar_close()` after using it. If opening the file or allocating the struct fails, returns NULL.
|
|
|
|
A `struct minitar` is opaque, and should only be passed to other minitar functions. You should not care about its contents.
|
|
|
|
### minitar_read_entry
|
|
`struct minitar_entry* minitar_read_entry(struct minitar* mp)`
|
|
|
|
Reads the next entry from a `struct minitar` which should be the return value of a previous call to `minitar_open()`. The return value is a heap-allocated `struct minitar_entry`, which should be freed with `minitar_free_entry()` when no longer needed.
|
|
|
|
This structure consists of the file metadata (in the `metadata` field), and a heap-allocated pointer to the file's contents (the `ptr` field), of size metadata.size + a NULL character, for convenience. This means you can use normal C string functions if you're expecting an ASCII file. Other kinds of files may have NULL characters before the end of the file, so you should assume the length of `ptr` is `metadata.size` and not `strlen(ptr)`.
|
|
|
|
This pointer will be freed when calling `minitar_free_entry()`, so if you're intending to use it later, copy its contents somewhere else.
|
|
|
|
This function returns NULL on end-of-file (when all entries have been read).
|
|
|
|
### minitar_free_entry
|
|
`void minitar_free_entry(struct minitar_entry* entry)`
|
|
|
|
Frees the heap-allocated `struct minitar_entry` and the file contents stored inside it. The pointer passed to `minitar_free_entry()` should be the return value of a previous call to `minitar_read_entry()`.
|
|
|
|
### minitar_rewind
|
|
`void minitar_rewind(struct minitar* mp)`
|
|
|
|
Rewinds the `struct minitar` back to the beginning of the archive file, which means that the next call to `minitar_read_entry()` will return the first entry instead of the entry after the last read entry.
|
|
|
|
### minitar_close
|
|
`int minitar_close(struct minitar* mp)`
|
|
|
|
Closes the tar archive file `mp` points to and frees the heap memory it was using. The pointer passed to `minitar_close()` should be the return value of a previous call to `minitar_open()`.
|
|
|
|
Returns 0 on success, everything else is failure and you should check `errno`. |