diff options
-rw-r--r-- | xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java b/xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java new file mode 100644 index 0000000..be9110d --- /dev/null +++ b/xtra4j-misc/src/main/java/ch/hiddenalpha/xtra4j/file/File.java @@ -0,0 +1,70 @@ +package ch.hiddenalpha.xtra4j.file; + +import java.io.IOException; + + +public interface File { + + /** + * <p>Based on <a href="https://pubs.opengroup.org/onlinepubs/009695399/functions/fread.html"> + * POSIX fread</a>. Nevertheless there are some differences (keep reading below).</p> + * + * <p>If at least one of 'off', 'size' or 'count' is negative, behavior is + * undefined</p> + * + * <p>If 'size' times 'count' is outside range 0 to INT_MAX, behavior is + * undefined.</p> + * + * <p>If 'off', 'size' and 'count' provocate to write outside bounds of given + * 'buf', behavior is undefined.</p> + * + * @param buf + * Buffer where requested data gets written to. MUST NOT be null. + * @param off + * Index of buf where the first byte gets written. + * @param size + * Size in bytes of one element. If you don't care, pass 1. + * @param count + * How many times 'size' bytes get read maximally. + * @return + * Count of read elements. This equals to bytes if 'size' is 1. Be aware + * that in future, this may return negative values. For now those are + * not defined but a caller has to be aware that this may be the case + * in future. + */ + int read(byte[] buf, int off, int size, int count) throws IOException; + + /** + * <p>Based on <a href="https://pubs.opengroup.org/onlinepubs/009695399/functions/fwrite.html"> + * POSIX fwrite</a></p>. + * + * <p>Caller has to ensure that combination of passed arguments always stay + * inside bounds and especially that 'size' times 'count' does NOT overflow. + * Ignoring those, results in undefined behavior.</p> + * + * @param buf + * Buffer holding the data to write. + * @param off + * Index of 'buf' where first byte gets read from. + * @param size + * Size in bytes of one element. If you don't care, pass 1. + * @param count + * How many elements of size 'size' are to read. + * @return + * Count of written elements. This equals to bytes if 'size' is 1. For + * now those are not defined but a caller has to be aware that this may + * be the case in future. + */ + int write(byte[] buf, int off, int size, int count) throws IOException; + + /** + * <p>Based on <a href="https://pubs.opengroup.org/onlinepubs/009695399/functions/fseek.html"> + * POSIX fseek</a>.</p> + * + * @param offset + * @param whence + * @return + */ + int fseek(long offset, int whence); + +} |