Convert README to markdown

2 files changed, 19 insertions, 163 deletions

diff --git a/README b/README
deleted file mode 100644
index 180d2845..00000000
--- a/README
+++ /dev/null
@@ -1,163 +0,0 @@
-README for libarchive bundle.
-
-Questions?  Issues?
-   * http://www.libarchive.org is the home for ongoing
-     libarchive development, including documentation, and
-     links to the libarchive mailing lists.
-   * To report an issue, use the issue tracker at
-     https://github.com/libarchive/libarchive/issues
-   * To submit an enhancement to libarchive, please submit
-     a pull request via GitHub.
-     https://github.com/libarchive/libarchive/pulls
-
-This distribution bundle includes the following components:
-   * libarchive: a library for reading and writing streaming archives
-   * tar: the 'bsdtar' program is a full-featured 'tar'
-          implementation built on libarchive
-   * cpio: the 'bsdcpio' program is a different interface to
-          essentially the same functionality
-   * cat: the 'bsdcat' program is a simple replacement tool for
-          zcat, bzcat, xzcat, and such
-   * examples: Some small example programs that you may find useful.
-   * examples/minitar: a compact sample demonstrating use of libarchive.
-   * contrib:  Various items sent to me by third parties;
-          please contact the authors with any questions.
-
-The top-level directory contains the following information files:
-   * NEWS - highlights of recent changes
-   * COPYING - what you can do with this
-   * INSTALL - installation instructions
-   * README - this file
-   * configure - configuration script, see INSTALL for details.
-   * CMakeLists.txt - input for "cmake" build tool, see INSTALL
-
-The following files in the top-level directory are used by the
-'configure' script:
-   * Makefile.am, aclocal.m4, configure.ac
-       - used to build this distribution, only needed by maintainers
-   * Makefile.in, config.h.in
-	- templates used by configure script
-
-Guide to Documentation installed by this system:
- * bsdtar.1 explains the use of the bsdtar program
- * bsdcpio.1 explains the use of the bsdcpio program
- * bsdcat.1 explains the use of the bsdcat program
- * libarchive.3 gives an overview of the library as a whole
- * archive_read.3, archive_write.3, archive_write_disk.3, and
-   archive_read_disk.3 provide detailed calling sequences for the read
-   and write APIs
- * archive_entry.3 details the "struct archive_entry" utility class
- * archive_internals.3 provides some insight into libarchive's
-   internal structure and operation.
- * libarchive-formats.5 documents the file formats supported by the library
- * cpio.5, mtree.5, and tar.5 provide detailed information about these
-   popular archive formats, including hard-to-find details about
-   modern cpio and tar variants.
-The manual pages above are provided in the 'doc' directory in
-a number of different formats.
-
-You should also read the copious comments in "archive.h" and the
-source code for the sample programs for more details.  Please let us
-know about any errors or omissions you find.
-
-Currently, the library automatically detects and reads the following fomats:
-  * GNU tar format (including GNU long filenames, long link names, and sparse files)
-  * Solaris 9 extended tar format (including ACLs)
-  * Old V7 tar archives
-  * POSIX ustar
-  * POSIX pax interchange format
-  * POSIX octet-oriented cpio
-  * SVR4 ASCII cpio
-  * POSIX octet-oriented cpio
-  * Binary cpio (big-endian or little-endian)
-  * ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions)
-  * ZIP archives (with uncompressed or "deflate" compressed entries)
-  * GNU and BSD 'ar' archives
-  * 'mtree' format
-  * 7-Zip archives
-  * Microsoft CAB format
-  * LHA and LZH archives
-  * RAR archives
-  * XAR archives
-
-The library also detects and handles any of the following before evaluating the archive:
-  * uuencoded files
-  * files with RPM wrapper
-  * gzip compression
-  * bzip2 compression
-  * compress/LZW compression
-  * lzma, lzip, and xz compression
-  * lz4 compression
-  * lzop compression
-
-The library can create archives in any of the following formats:
-  * POSIX ustar
-  * POSIX pax interchange format
-  * "restricted" pax format, which will create ustar archives except for
-    entries that require pax extensions (for long filenames, ACLs, etc).
-  * Old GNU tar format
-  * Old V7 tar format
-  * POSIX octet-oriented cpio
-  * SVR4 "newc" cpio
-  * shar archives
-  * ZIP archives (with uncompressed or "deflate" compressed entries)
-  * GNU and BSD 'ar' archives
-  * 'mtree' format
-  * ISO9660 format
-  * 7-Zip archives
-  * XAR archives
-
-When creating archives, the result can be filtered with any of the following:
-  * uuencode
-  * gzip compression
-  * bzip2 compression
-  * compress/LZW compression
-  * lzma, lzip, and xz compression
-  * lz4 compression
-  * lzop compression
-
-Notes about the library architecture:
-
- * This is a heavily stream-oriented system.  There is no direct
-   support for in-place modification or random access.
-
- * The library is designed to be extended with new compression and
-   archive formats.  The only requirement is that the format be
-   readable or writable as a stream and that each archive entry be
-   independent.  There are articles on the libarchive Wiki explaining
-   how to extend libarchive.
-
- * On read, compression and format are always detected automatically.
-
- * I've attempted to minimize static link pollution.  If you don't
-   explicitly invoke a particular feature (such as support for a
-   particular compression or format), it won't get pulled in to
-   statically-linked programs.  In particular, if you don't explicitly
-   enable a particular compression or decompression support, you won't
-   need to link against the corresponding compression or decompression
-   libraries.  This also reduces the size of statically-linked
-   binaries in environments where that matters.
-
- * On read, the library accepts whatever blocks you hand it.
-   Your read callback is free to pass the library a byte at a time
-   or mmap the entire archive and give it to the library at once.
-   On write, the library always produces correctly-blocked output.
-
- * The object-style approach allows you to have multiple archive streams
-   open at once.  bsdtar uses this in its "@archive" extension.
-
- * The archive itself is read/written using callback functions.
-   You can read an archive directly from an in-memory buffer or
-   write it to a socket, if you wish.  There are some utility
-   functions to provide easy-to-use "open file," etc, capabilities.
-
- * The read/write APIs are designed to allow individual entries
-   to be read or written to any data source:  You can create
-   a block of data in memory and add it to a tar archive without
-   first writing a temporary file.  You can also read an entry from
-   an archive and write the data directly to a socket.  If you want
-   to read/write entries to disk, there are convenience functions to
-   make this especially easy.
-
- * Note: "pax interchange format" is really an extended tar format,
-   despite what the name says.
diff --git a/README.md b/README.md
index 1b87069f..baff22c6 100644
--- a/README.md
+++ b/README.md
@@ -128,6 +128,9 @@ When creating archives, the result can be filtered with any of the following:
 
 ## Notes about the Library Design
 
+The following notes address many of the most common
+questions we are asked about libarchive:
+
 * This is a heavily stream-oriented system.  That means that
   it is optimized to read or write the archive in a single
   pass from beginning to end.  For example, this allows
@@ -173,6 +176,22 @@ When creating archives, the result can be filtered with any of the following:
   libraries.  This also reduces the size of statically-linked
   binaries in environments where that matters.
 
+* The library is generally _thread safe_ depending on the platform:
+  it does not define any global variables of its own.  However, some
+  platforms do not provide fully thread-safe versions of key C library
+  functions.  On those platforms, libarchive will use the non-thread-safe
+  functions.  Patches to improve this are of great interest to us.
+
+* In particular, libarchive's modules to read or write a directory
+  tree do use `chdir()` to optimize the directory traversals.  This
+  can cause problems for programs that expect to do disk access from
+  multiple threads.
+
+* The library is _not_ thread aware, however.  It does no locking
+  or thread management of any kind.  If you create a libarchive
+  object and need to access it from multiple threads, you will
+  need to provide your own locking.
+
 * On read, the library accepts whatever blocks you hand it.
   Your read callback is free to pass the library a byte at a time
   or mmap the entire archive and give it to the library at once.