start putting dirutils in its own place

libdirutils/README.md

@@ -0,0 +1,120 @@
+Introduction
+============
+
+`libdirutils` is a utility library inspired by similar functionality in
+the Go and Python programming languages; it provides functions similar
+to `rm -r` and `mkdir -p`, as well as a convenience function to combine
+the functionality of `access(2)` and `stat(2)`.
+
+Functions Provided
+==================
+
+makedirs
+--------
+
+    int
+    makedirs(const char *path);
+
+`makedirs` creates a path and all required parent directories. The mode
+created is the process’s `umask(2)` value applied to `0777`. It returns
+`EXIT_SUCCESS` on success and `EXIT_FAILURE` on failure.
+
+rmdirs
+------
+
+    int
+    rmdirs(const char *path);
+
+`rmdirs` removes a path and all subdirectories and files. It returns
+`EXIT_SUCCESS` on success and `EXIT_FAILURE` on failure.
+
+path\_exists
+------------
+
+    EXISTS_STATUS
+    path_exists(const char *path);
+
+`path_exists` combines the functionality of `access(2)` and `stat(2)`.
+It checks whether the process has access to the file and indicates
+whether it is a regular file, a directory, or if an error occurs. The
+return type is of the enumeration `EXISTS_STATUS`, which is one of
+
+*   `EXISTS_ERROR`: there was an error looking up the file;
+
+*   `EXISTS_NOENT`: the file does not exist;
+
+*   `EXISTS_NOPERM`: the process does not have the appropriate
+    permissions to access the file.
+
+*   `EXISTS_DIR`: the file is a direcotry;
+
+*   `EXISTS_FILE`: the file is a regular file; and
+
+*   `EXISTS_OTHER`: the file could be read and is not a directory or
+    regular file.
+
+Getting the Source
+==================
+
+Dependencies
+------------
+
+If you will be running the unit tests, `CUnit`[^1] is required. If you
+will be rebuilding the autotools build infrastructure, you will need
+automake 1.11 and autoconf >= 2.59.
+
+Development Repository
+----------------------
+
+The source code repository is available on Github[^2]. The code there is
+in the original autotools source; the `autobuild.sh` script is provided
+to run through a complete build, including running through the provided
+unit tests:
+
+    $ git clone https://github.com/kisom/libdirutils.git dirutils
+    $ cd dirutils
+    $ ./autobuild.sh
+
+Several utility scripts are provided in the `scripts` subdirectory; the
+`autobuild.sh` script calls these. Of note, the `prebuild.sh` script,
+which will set the necessary autotools environment variables and call
+`autoreconf`.
+
+Release Tarballs
+----------------
+
+Release tarballs will be made available via the Github repository’s
+downloads[^3] section.
+
+Once unpacked, these can be built with the normal
+
+        ./configure && make && make install
+
+method. See
+
+        ./configure --help
+
+for additional configuration options.
+
+License
+=======
+
+    Copyright (c) 2012 Kyle Isom <kyle@tyrfingr.is>
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above 
+    copyright notice and this permission notice appear in all copies.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 
+
+[^1]: http://cunit.sourceforge.net/
+
+[^2]: https://github.com/kisom/libdirutils
+
+[^3]: https://github.com/kisom/libdirutils/downloads