Add docs on file utilities

lib/Utils.md

@@ -9,6 +9,7 @@ The OpenCL Utility Library provides both C and C++ bindings with near feature pa
 - [Context](#context-utilities)
 - [Event](#event-utilities)
 - [Error](#error-handling-utilities)
+- [File](#file-utilities)
 
 ### Platform utilities
 
@@ -119,3 +120,97 @@ public:
 };
 ```
 This type is used as the exception type thrown by utilities when an error occurs and the compiling code defines `CL_HPP_ENABLE_EXCEPTIONS`
+
+### File utilities
+
+```c
+char* cl_util_read_text_file(
+    const char* const filename,
+    size_t* const length,
+    cl_int* const error);
+```
+
+```c++
+std::string cl::util::read_text_file(
+    const char* const filename,
+    cl_int* const error = nullptr);
+```
+
+These functions read a text file into memory, where `filename` is evaluated relative to the current working directory. The C-version contains a terminating null and takes an optional pointer to `length` by which the length my be returned, potentially saving a subsequent call to `strlen`. The function hands ownership of the allocated storage to the caller.
+
+```c
+unsigned char* cl_util_read_binary_file(
+    const char* const filename,
+    size_t* const length,
+    cl_int* const error);
+```
+
+```c++
+std::vector<unsigned char> read_binary_file(
+    const char* const filename,
+    cl_int* const error = nullptr);
+```
+
+These functions read a binary file into memory, where `filename` is evaluated relative to the current working directory. The C-version takes an optional pointer to `length` by which the length my be returned. Beause it's binary data, it is _not_ null-terminated, therefore highly recommended to take it's size. The returned types align with OpenCL APIs taking binaries as input. The function hands ownership of the allocated storage to the caller.
+
+```c
+cl_program cl_util_read_binaries(
+    const cl_context context,
+    const cl_device_id* const devices,
+    const cl_uint num_devices,
+    const char* const program_file_name,
+    cl_int* const error
+);
+```
+
+```c++
+Program::Binaries read_binary_files(
+    const std::vector<cl::Device>& devices,
+    const char* const program_file_name,
+    cl_int* const error = nullptr);
+```
+
+These functions read a set of binary files into memory. `program_file_name` is a pattern that will be completed for every input device using the `"(program_file_name)_(name of device).bin"` pattern. If any of the files are not found, the function fails.
+
+```c
+cl_int cl_util_write_binaries(
+    const cl_program program,
+    const char* const program_file_name);
+```
+
+```c++
+write_binaries(
+    const cl::Program::Binaries& binaries,
+    const std::vector<cl::Device>& devices,
+    const char* const program_file_name);
+```
+
+These functions will write all device binaries of a program to persistent storage. `program_file_name` is a pattern that will be completed for every input device using the `"(program_file_name)_(name of device).bin"` pattern.
+
+```c
+cl_int cl_util_executable_folder(
+    char* filename,
+    size_t* const length);
+```
+
+```c++
+std::string executable_folder(
+    cl_int* const error = nullptr);
+```
+
+These functions return the path to the folder containing the currently running executable. It is typically useful to find assets which are stored uniformly in a program's build and install tree. The C-version contains a terminating null and takes an optional pointer to `length` by which the length my be returned, potentially saving a subsequent call to `strlen`.
+
+```c
+char* cl_util_read_exe_relative_text_file(
+    const char* const rel_path,
+    size_t* const length,
+    cl_int* const error);
+```
+
+```c++
+std::string read_exe_relative_text_file(
+    const char* const filename,
+    cl_int* const error = nullptr);
+```
+
+These functions read a text file into memory, where `filename` is evaluated relative to the executable currently running. The C-version contains a terminating null and takes an optional pointer to `length` by which the length my be returned, potentially saving a subsequent call to `strlen`. The function hands ownership of the allocated storage to the caller.