Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | Download | RSS feed

  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.
  100.