1# microtar
 2A lightweight tar library written in ANSI C
 3
 4
 5## Basic Usage
 6The library consists of `microtar.c` and `microtar.h`. These two files can be
 7dropped into an existing project and compiled along with it.
 8
 9
10#### Reading
11```c
12mtar_t tar;
13mtar_header_t h;
14char *p;
15
16/* Open archive for reading */
17mtar_open(&tar, "test.tar", "r");
18
19/* Print all file names and sizes */
20while ( (mtar_read_header(&tar, &h)) != MTAR_ENULLRECORD ) {
21  printf("%s (%d bytes)\n", h.name, h.size);
22  mtar_next(&tar);
23}
24
25/* Load and print contents of file "test.txt" */
26mtar_find(&tar, "test.txt", &h);
27p = calloc(1, h.size + 1);
28mtar_read_data(&tar, p, h.size);
29printf("%s", p);
30free(p);
31
32/* Close archive */
33mtar_close(&tar);
34```
35
36#### Writing
37```c
38mtar_t tar;
39const char *str1 = "Hello world";
40const char *str2 = "Goodbye world";
41
42/* Open archive for writing */
43mtar_open(&tar, "test.tar", "w");
44
45/* Write strings to files `test1.txt` and `test2.txt` */
46mtar_write_file_header(&tar, "test1.txt", strlen(str1));
47mtar_write_data(&tar, str1, strlen(str1));
48mtar_write_file_header(&tar, "test2.txt", strlen(str2));
49mtar_write_data(&tar, str2, strlen(str2));
50
51/* Finalize -- this needs to be the last thing done before closing */
52mtar_finalize(&tar);
53
54/* Close archive */
55mtar_close(&tar);
56```
57
58
59## Error handling
60All functions which return an `int` will return `MTAR_ESUCCESS` if the operation
61is successful. If an error occurs an error value less-than-zero will be
62returned; this value can be passed to the function `mtar_strerror()` to get its
63corresponding error string.
64
65
66## Wrapping a stream
67If you want to read or write from something other than a file, the `mtar_t`
68struct can be manually initialized with your own callback functions and a
69`stream` pointer.
70
71All callback functions are passed a pointer to the `mtar_t` struct as their
72first argument. They should return `MTAR_ESUCCESS` if the operation succeeds
73without an error, or an integer below zero if an error occurs.
74
75After the `stream` field has been set, all required callbacks have been set and
76all unused fields have been zeroset the `mtar_t` struct can be safely used with
77the microtar functions. `mtar_open` *should not* be called if the `mtar_t`
78struct was initialized manually.
79
80#### Reading
81The following callbacks should be set for reading an archive from a stream:
82
83Name    | Arguments                                | Description
84--------|------------------------------------------|---------------------------
85`read`  | `mtar_t *tar, void *data, unsigned size` | Read data from the stream
86`seek`  | `mtar_t *tar, unsigned pos`              | Set the position indicator
87`close` | `mtar_t *tar`                            | Close the stream
88
89#### Writing
90The following callbacks should be set for writing an archive to a stream:
91
92Name    | Arguments                                      | Description
93--------|------------------------------------------------|---------------------
94`write` | `mtar_t *tar, const void *data, unsigned size` | Write data to the stream
95
96
97## License
98This library is free software; you can redistribute it and/or modify it under
99the terms of the MIT license. See [LICENSE](LICENSE) for details.