fix naming and add documentation

README.md

@@ -0,0 +1,42 @@
+# remove\_all
+> C replication of `std::filesystem::remove_all` of C++17.
+
+## SYNOPSIS
+
+    #include <remove_all.h>
+
+    int remove_all(const char * const p);
+
+## DESCRIPTION
+Deletes the contents of `p` (if it is a directory)
+and the contents of all its subdirectories, recursively,
+then deletes `p` itself as if by repeatedly applying the POSIX remove.
+Symlinks are not followed (symlink is removed, not its target).
+
+## RETURN VALUE
+On success, zero is returned.
+On error, -1 is returned, and errno is set  to  indicate the error.
+
+## ERRORS
+The errors that occur are those for unlink(2) and rmdir(2).
+
+## ATTRIBUTES
+For an explanation of the terms used in this section, see attributes(7).
+
+| Interface | Attribute | Value |
+| :---: |  :---: | :---: |
+| rename\_all() | Thread safety | MT-Safe |
+
+## BUGS
+Infelicities in  the protocol underlying NFS
+can cause the unexpected disappearance of files
+which are still being used.
+
+## SEE ALSO
+`remove`(2),
+`unlink`(2),
+`rmdir`(2),
+
+## NOTES
+The C++ `remove_all` returns the number of deleted files,
+we instead copy the return value schema of POSIX (and `remove(3)`).

filesystem_remove.h

@@ -1,10 +0,0 @@
-#ifndef FILESYSTEM_REMOVE
-#define FILESYSTEM_REMOVE
-#include <stdbool.h>
-
-/* C replication of `std::filesystem::remove` of C++17
- * Unlike standard C remove(3), it can remove recursively.
- */
-bool filesystem_remove(const char * const p);
-
-#endif

remove_all.c

@@ -1,4 +1,4 @@
-#include "filesystem_remove.h"
+#include "remove_all.h"
 
 #define _XOPEN_SOURCE 500
 #include <stdio.h>
@@ -21,11 +21,11 @@ int remove_wrapper(
     return 0;
 }
 
-bool filesystem_remove(const char * const p) {
+int remove_all(const char * const p) {
     #define NOPENFD 256
     const int result = nftw(p, remove_wrapper, NOPENFD, FTW_DEPTH | FTW_PHYS);
-    if (result) { return false; }
+    if (result) { return 1; }
 
-    return true;
+    return 0;
     #undef NOPENFD
 }

remove_all.h

@@ -0,0 +1,9 @@
+#ifndef REMOVE_ALL_H
+#define REMOVE_ALL_H
+
+/* C replication of `std::filesystem::remove` of C++17.
+ * Unlike standard C remove(3), it can remove recursively.
+ */
+int remove_all(const char * const p);
+
+#endif

test.c

@@ -1,6 +1,6 @@
-// @BAKE gcc -o $*.out $@ filesystem_remove.c -ggdb
-#include "filesystem_remove.h"
+// @BAKE gcc -o $*.out $@ remove_all.c -ggdb
+#include "remove_all.h"
 
 signed main(void) {
-    return !filesystem_remove("testdir/");
+    return remove_all("testdir/");
 }