kst/libdirutils/README.md

121 lines
3.5 KiB
Markdown
Raw Normal View History

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 processs `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 repositorys
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