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