qfs 0.0.13

data/ext/qfs/file.h

@@ -0,0 +1,19 @@
+#ifndef QFS_EXT_FILE_H_
+#define QFS_EXT_FILE_H_
+
+#include <ruby.h>
+
+extern VALUE cQfsFile;
+
+struct qfs_file {
+	VALUE client;
+	int fd;
+};
+
+void qfs_file_deallocate(void*);
+void qfs_file_mark(void*);
+VALUE qfs_file_allocate(VALUE);
+
+void init_qfs_ext_file(void);
+
+#endif // QFS_FILE_H_

data/ext/qfs/qfs.c

@@ -0,0 +1,367 @@
+#include "qfs.h"
+
+#include <ruby.h>
+#include "attr.h"
+#include "file.h"
+#include "util.h"
+
+// This is the base size of a buffer to contain the working directory
+#ifndef BASE_WD_BUFFER_SIZE
+#define BASE_WD_BUFFER_SIZE 512
+#endif
+
+// The maximum size this buffer should ever grow to (10kb)
+#ifndef MAX_WD_BUFFER_SIZE
+#define MAX_WD_BUFFER_SIZE 4096
+#endif
+
+VALUE mQfs;
+VALUE eQfsError;
+
+static VALUE cQfsBaseClient;
+
+// Ruby Errno::* exceptions
+VALUE rb_eErrnoENOENT;
+VALUE rb_eErrnoENAMETOOLONG;
+
+/* qfs_client */
+
+static void qfs_client_deallocate(void *qfsvp) {
+	TRACE;
+	struct qfs_client *qfs = qfsvp;
+	if (qfs->qfs) {
+		qfs_release(qfs->qfs);
+		qfs->qfs = NULL;
+	}
+	free(qfs);
+	TRACE_R;
+}
+
+static VALUE qfs_client_allocate(VALUE klass) {
+	struct qfs_client *qfs = malloc(sizeof(struct qfs_client));
+	qfs->qfs = NULL;
+	return Data_Wrap_Struct(klass, NULL, qfs_client_deallocate, qfs);
+}
+
+/* qfs_connect wrapper. Raises Qfs::Error on error */
+static VALUE qfs_client_connect(VALUE self, VALUE host, VALUE port) {
+	struct qfs_client *qfs;
+	Check_Type(host, T_STRING);
+	Check_Type(port, T_FIXNUM);
+	Data_Get_Struct(self, struct qfs_client, qfs);
+	qfs->qfs = qfs_connect(StringValueCStr(host), FIX2INT(port));
+	if (!qfs->qfs) {
+		rb_raise(eQfsError, "Connection failed");
+	}
+	return Qnil;
+}
+
+/* qfs_release wrapper */
+static VALUE qfs_client_release(VALUE self) {
+	TRACE;
+	struct qfs_client *qfs;
+	Data_Get_Struct(self, struct qfs_client, qfs);
+	if (qfs->qfs) {
+		qfs_release(qfs->qfs);
+	}
+	qfs->qfs = NULL;
+	TRACE_R;
+	return Qnil;
+}
+
+static VALUE qfs_client_open(int argc, VALUE *argv, VALUE self) {
+	struct qfs_client *client;
+	VALUE path;
+	VALUE oflag;
+	VALUE mode;
+	VALUE params;
+	rb_scan_args(argc, argv, "13", &path, &oflag, &mode, &params);
+	Check_Type(path, T_STRING);
+	int ioflag;
+	uint16_t imode;
+	char *sparams;
+	if (oflag == Qnil) {
+		ioflag = O_RDONLY;
+	} else {
+		Check_Type(oflag, T_FIXNUM);
+		ioflag = FIX2INT(oflag);
+	}
+	if (mode == Qnil) {
+		imode = 0666;
+	} else {
+		Check_Type(mode, T_FIXNUM);
+		imode = (uint16_t)FIX2INT(mode);
+	}
+	if (params == Qnil) {
+		sparams = NULL;
+	} else {
+		Check_Type(params, T_STRING);
+		sparams = StringValueCStr(params);
+	}
+
+	Data_Get_Struct(self, struct qfs_client, client);
+	int fd = qfs_open_file(client->qfs, StringValueCStr(path), ioflag, imode, sparams);
+	QFS_CHECK_ERR(fd);
+	struct qfs_file *file = ALLOC(struct qfs_file);
+	file->client = self;
+	file->fd = fd;
+	return Data_Wrap_Struct(cQfsFile, qfs_file_mark, qfs_file_deallocate, file);
+}
+
+static VALUE qfs_client_readdir(VALUE self, VALUE path) {
+	int left;
+	int count = 0;
+	Check_Type(path, T_STRING);
+	char *p = StringValueCStr(path);
+	struct qfs_iter *iter = NULL;
+	struct qfs_attr attr;
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	while ((left = qfs_readdir(client->qfs, p, &iter, &attr)) > 0) {
+		struct qfs_attr *tmp_attr = ALLOC(struct qfs_attr);
+		memcpy(tmp_attr, &attr, sizeof(attr));
+		count += 1;
+		rb_yield(Data_Wrap_Struct(cQfsAttr, NULL, free, tmp_attr));
+	}
+	qfs_iter_free(&iter);
+	QFS_CHECK_ERR(left);
+	return INT2FIX(count);
+}
+
+static VALUE qfs_client_path_checking(VALUE self, VALUE path,
+		bool (*check_func)(struct QFS*, const char*)) {
+	Check_Type(path, T_STRING);
+	char *p = StringValueCStr(path);
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	bool exists = (*check_func)(client->qfs, p);
+	return INT2BOOL(exists);
+}
+
+static VALUE qfs_client_exists(VALUE self, VALUE path) {
+	return qfs_client_path_checking(self, path, qfs_exists);
+}
+
+static VALUE qfs_client_isfile(VALUE self, VALUE path) {
+	return qfs_client_path_checking(self, path, qfs_isfile);
+}
+
+static VALUE qfs_client_isdirectory(VALUE self, VALUE path) {
+	return qfs_client_path_checking(self, path, qfs_isdirectory);
+}
+
+static VALUE qfs_client_remove(VALUE self, VALUE path) {
+	Check_Type(path, T_STRING);
+	char *p = StringValueCStr(path);
+
+	// Check that the file is regular
+	VALUE isfile = qfs_client_isfile(self, path);
+	if (!RTEST(isfile)) {
+		rb_raise(eQfsError, "Not a regular file - %s", p);
+	}
+
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	int res = qfs_remove(client->qfs, p);
+
+	// Raise an exception if the file didn't exist
+	if (res == -2) {
+		rb_raise(rb_eErrnoENOENT, "No such file or directory - %s", p);
+	}
+
+	QFS_CHECK_ERR(res);
+	return INT2NUM(1);
+}
+
+static VALUE qfs_client_mkdir_base(VALUE self, VALUE path, VALUE mode,
+		int (*mkdir_func)(struct QFS*, const char*, mode_t)) {
+	Check_Type(path, T_STRING);
+	char *p = StringValueCStr(path);
+
+	// check if the directory already exists
+	if (RTEST(qfs_client_exists(self, path))) {
+		rb_raise(eQfsError, "File exists - %s", p);
+	}
+
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	Check_Type(mode, T_FIXNUM);
+	uint16_t imode = (uint16_t)FIX2INT(mode);
+	int res = (*mkdir_func)(client->qfs, p, imode);
+	QFS_CHECK_ERR(res);
+	return RES2BOOL(res);
+}
+
+static VALUE qfs_client_mkdir(VALUE self, VALUE path, VALUE mode) {
+	return qfs_client_mkdir_base(self, path, mode, qfs_mkdir);
+}
+
+static VALUE qfs_client_mkdir_p(VALUE self, VALUE path, VALUE mode) {
+	return qfs_client_mkdir_base(self, path, mode, qfs_mkdirs);
+}
+
+static VALUE qfs_client_rmdir_base(VALUE self, VALUE path,
+		int (*rmdir_func)(struct QFS*, const char*)) {
+	Check_Type(path, T_STRING);
+	char *p = StringValueCStr(path);
+
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	int res = (*rmdir_func)(client->qfs, p);
+
+	// Raise an exception if the file didn't exist
+	if (res == -2) {
+		rb_raise(rb_eErrnoENOENT, "No such file or directory - %s", p);
+	}
+
+	QFS_CHECK_ERR(res);
+	return INT2NUM(res);
+}
+
+static VALUE qfs_client_rmdir(VALUE self, VALUE path) {
+	return qfs_client_rmdir_base(self, path, qfs_rmdir);
+}
+
+static VALUE qfs_client_rmdirs(VALUE self, VALUE path) {
+	return qfs_client_rmdir_base(self, path, qfs_rmdirs);
+}
+
+// Making multiple stat calls against the same file appears to return the
+// same result, event if the properties change.  This can be reproduced by
+// the permissions on a file, stat'ing it, setting the permissions to something
+// else, and stat'ing it again.  This appears to be a property of the
+// QFS C api.
+static VALUE qfs_client_stat(VALUE self, VALUE path) {
+	Check_Type(path, T_STRING);
+	char *p = StringValueCStr(path);
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	struct qfs_attr *attr = ALLOC(struct qfs_attr);
+	int res = qfs_stat(client->qfs, p, attr);
+	QFS_CHECK_ERR(res);
+	return Data_Wrap_Struct(cQfsAttr, NULL, free, attr);
+}
+
+static VALUE qfs_client_chmod_base(VALUE self, VALUE path, VALUE mode,
+		int (*chmod_func)(struct QFS*, const char*, mode_t)) {
+	Check_Type(path, T_STRING);
+	Check_Type(mode, T_FIXNUM);
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	char *p = StringValueCStr(path);
+	uint16_t imode = (uint16_t)FIX2INT(mode);
+	int res = (*chmod_func)(client->qfs, p, imode);
+	QFS_CHECK_ERR(res);
+	return RES2BOOL(res);
+}
+
+static VALUE qfs_client_chmod(VALUE self, VALUE path, VALUE mode) {
+	return qfs_client_chmod_base(self, path, mode, qfs_chmod);
+}
+
+static VALUE qfs_client_chmod_r(VALUE self, VALUE path, VALUE mode) {
+	return qfs_client_chmod_base(self, path, mode, qfs_chmod_r);
+}
+
+static VALUE qfs_client_rename(VALUE self, VALUE old, VALUE new) {
+	Check_Type(old, T_STRING);
+	Check_Type(new, T_STRING);
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	char *old_s = StringValueCStr(old);
+	char *new_s = StringValueCStr(new);
+	int res = qfs_rename(client->qfs, old_s, new_s);
+	QFS_CHECK_ERR(res);
+	return RES2BOOL(res);
+}
+
+static VALUE qfs_set_attribute_revalidate_time(VALUE self, VALUE seconds) {
+	Check_Type(seconds, T_FIXNUM);
+	int secs = FIX2INT(seconds);
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	qfs_set_fileattributerevalidatetime(client->qfs, secs);
+	return Qnil;
+}
+
+static VALUE qfs_client_cd_base(VALUE self, VALUE path,
+		int (*cd_func)(struct QFS*, const char*)) {
+	Check_Type(path, T_STRING);
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+	char *p = StringValueCStr(path);
+	int res = cd_func(client->qfs, p);
+	QFS_CHECK_ERR(res);
+	return Qnil;
+}
+
+static VALUE qfs_client_cd(VALUE self, VALUE path) {
+	return qfs_client_cd_base(self, path, qfs_cd);
+}
+
+static VALUE qfs_client_setwd(VALUE self, VALUE path) {
+	return qfs_client_cd_base(self, path, qfs_setwd);
+}
+
+static VALUE qfs_client_getwd(VALUE self) {
+	struct qfs_client *client;
+	Data_Get_Struct(self, struct qfs_client, client);
+
+	size_t n = (size_t)BASE_WD_BUFFER_SIZE;
+	while (n < (size_t)MAX_WD_BUFFER_SIZE) {
+		VALUE str = rb_str_buf_new((long)n);
+		int len_read = qfs_getwd(client->qfs, RSTRING_PTR(str), n);
+		QFS_CHECK_ERR(len_read);
+		// Return if the entire WD was read into the buffer
+		if (len_read < (int)n) {
+			rb_str_set_len(str, len_read);
+			return str;
+		}
+
+		n = n * 2; // Grow the buffer
+	}
+
+	// The path was too long, raise an exception.  This is just a sanity
+	// check, in practice there is no reason that a path should be greater
+	// than 10kb in size.
+	rb_raise(rb_eErrnoENAMETOOLONG, "Working directory path too long");
+}
+
+void Init_qfs_ext() {
+	mQfs = rb_define_module("Qfs");
+
+	check_trace_enabled();
+
+	cQfsBaseClient = rb_define_class_under(mQfs, "BaseClient", rb_cObject);
+	rb_define_alloc_func(cQfsBaseClient, qfs_client_allocate);
+	rb_define_method(cQfsBaseClient, "initialize", qfs_client_connect, 2);
+	rb_define_method(cQfsBaseClient, "release", qfs_client_release, 0);
+	rb_define_method(cQfsBaseClient, "open", qfs_client_open, -1);
+	rb_define_method(cQfsBaseClient, "readdir", qfs_client_readdir, 1);
+	rb_define_method(cQfsBaseClient, "exists", qfs_client_exists, 1);
+	rb_define_method(cQfsBaseClient, "remove", qfs_client_remove, 1);
+	rb_define_method(cQfsBaseClient, "isfile", qfs_client_isfile, 1);
+	rb_define_method(cQfsBaseClient, "isdirectory", qfs_client_isdirectory, 1);
+	rb_define_method(cQfsBaseClient, "mkdir", qfs_client_mkdir, 2);
+	rb_define_method(cQfsBaseClient, "mkdir_p", qfs_client_mkdir_p, 2);
+	rb_define_method(cQfsBaseClient, "rmdir", qfs_client_rmdir, 1);
+	rb_define_method(cQfsBaseClient, "rmdirs", qfs_client_rmdirs, 1);
+	rb_define_method(cQfsBaseClient, "stat", qfs_client_stat, 1);
+	rb_define_method(cQfsBaseClient, "chmod", qfs_client_chmod, 2);
+	rb_define_method(cQfsBaseClient, "rename", qfs_client_rename, 2);
+	rb_define_method(cQfsBaseClient, "cd", qfs_client_cd, 1);
+	rb_define_method(cQfsBaseClient, "setwd", qfs_client_setwd, 1);
+	rb_define_protected_method(cQfsBaseClient, "cwd", qfs_client_getwd, 0);
+	rb_define_private_method(cQfsBaseClient, "chmod_r", qfs_client_chmod_r, 2);
+	rb_define_private_method(cQfsBaseClient, "set_attribute_revalidate_time",
+			qfs_set_attribute_revalidate_time, 1);
+
+	init_qfs_ext_file();
+	init_qfs_ext_attr();
+
+	eQfsError = rb_define_class_under(mQfs, "Error", rb_eStandardError);
+
+	// Get the errno exceptions
+	rb_eErrnoENOENT = rb_const_get(rb_mErrno, rb_intern("ENOENT"));
+	rb_eErrnoENAMETOOLONG = rb_const_get(rb_mErrno, rb_intern("ENAMETOOLONG"));
+}

data/ext/qfs/qfs.h

@@ -0,0 +1,20 @@
+#ifndef RUBY_QFS_H
+#define RUBY_QFS_H
+
+#include <sys/types.h>
+#include <sys/time.h>
+#include <kfs/c/qfs.h>
+#include <ruby.h>
+
+extern VALUE mQfs;
+extern VALUE eQfsError;
+
+// QFS structs
+
+struct qfs_client {
+	struct QFS *qfs;
+};
+
+void Init_qfs_ext(void);
+
+#endif

data/ext/qfs/qfs_ext.version

@@ -0,0 +1,8 @@
+{
+	global:
+		Init_qfs_ext;
+		rb_*;
+		ruby_*;
+	local:
+		*;
+};

data/ext/qfs/util.h

@@ -0,0 +1,29 @@
+#ifndef QFS_EXT_UTIL_H_
+#define QFS_EXT_UTIL_H_
+
+#define QFS_NIL_FD -1
+
+#include <ruby.h>
+
+static int QFS_TRACE_ENABLED = 0;
+static inline void check_trace_enabled() {
+	if (getenv("RUBY_QFS_TRACE")) {
+		QFS_TRACE_ENABLED = 1;
+	}
+}
+
+#define TRACE do { if (QFS_TRACE_ENABLED) fprintf(stderr, "TRACE: %s start\n", __func__); } while(0)
+#define TRACE_R do { if (QFS_TRACE_ENABLED) fprintf(stderr, "TRACE: %s end\n", __func__); } while(0)
+#define WARN(s) do { fprintf(stderr, "WARN: %s\n", s); } while(0)
+
+#define QFS_CHECK_ERR(i) do { if (i < 0) { \
+    char buf[512]; \
+    rb_raise(eQfsError, "%s", qfs_strerror((int)i, buf, 1024)); \
+    TRACE_R; return Qnil; \
+} } while (0)
+
+#define NTIME(x) rb_time_new(x.tv_sec, x.tv_usec)
+#define INT2BOOL(x) (x?Qtrue:Qfalse)
+#define RES2BOOL(x) (x>=0 ? Qtrue : Qfalse)
+
+#endif // QFS_EXT_UTIL_H_

data/lib/qfs.rb

@@ -0,0 +1,390 @@
+require 'qfs/version'
+require 'qfs_ext'
+require 'fcntl'
+
+##
+# Container module for QFS classes
+module Qfs
+  # supported oflags
+  O_CREAT = Fcntl::O_CREAT
+  O_EXCL = Fcntl::O_EXCL
+  O_RDWR = Fcntl::O_RDWR
+  O_RDONLY = Fcntl::O_RDONLY
+  O_WRONLY = Fcntl::O_WRONLY
+  O_TRUNC = Fcntl::O_TRUNC
+
+  # A higher-level Client to interact with QFS.  This attempts to use
+  # a similar interface to ruby's native IO functionality.
+  class Client < BaseClient
+    # Open a file on QFS.  This method uses a very similar interface to the
+    # 'open' method standard in ruby.
+    #
+    # Modes
+    #   * 'r': Read only
+    #   * 'w': Write only, overwrite or create new file
+    #   * 'a': Append to the file
+    #
+    # @param [String] path the path to the file
+    # @param [Int] mode_str One of the mode types above
+    # @option options [Int] :mode permissions to set on the file
+    # @option options [String] :params
+    #
+    # @return [File] a Qfs::File
+    # @yield [File] a Qfs::File
+    def open(path, mode_str, options = {})
+      flags = mode_to_flags(mode_str)
+      raise Qfs::Error, "#{mode_str} is not a valid mode string" if flags.nil?
+
+      mode ||= options[:mode]
+      params ||= options[:params]
+      f = super(path, flags, mode, params)
+
+      # If the file was opened in append mode, seek to the end to simulate
+      # O_APPEND behavior
+      f.seek(0, IO::SEEK_END) if mode_str == 'a'
+
+      return f unless block_given?
+
+      begin
+        yield f
+      ensure
+        f.close
+      end
+    end
+
+    # Open a connection on the specified host and post, and yield it
+    # to a block
+    #
+    # @example Open a connection and yield to a block
+    #   Qfs::Client.with_client('localhost', 10000) do |client|
+    #     client.write('/file', '')
+    #   end
+    #
+    # @param [String] host the hostname to connect to
+    # @param [Int] port the port to connect to
+    #
+    # @yield [Client] a new client
+    def self.with_client(host, port)
+      c = new(host, port)
+      begin
+        yield c
+      ensure
+        c.release
+      end
+    end
+
+    alias exists? exists
+    alias exist? exists?
+
+    alias file? isfile
+
+    alias directory? isdirectory
+
+    # Remove a regular file.  Pass 'true' to stop exceptions from
+    # being thrown if the file doesn't exist.
+    #
+    # @param [String] path the path to the file
+    # @param [Bool] force Wheather or not to throw an exception if file doesn't
+    #                     exist.
+    #
+    # @raise [Error] if force=false
+    #
+    # @return [Bool] if or if not the method succeeded
+    def remove(path, force = false)
+      force_remove(force) { super(path) }
+    end
+
+    # Create a directory
+    #
+    # @param [String] path the path to the directory to make
+    # @param [Int] mode the permissions to set on the new directory
+    #
+    # @return [Bool] if the directory was created
+    def mkdir(path, mode = 0o600)
+      super(path, mode)
+    end
+
+    # Create a directory and create parent directories if needed
+    #
+    # @param [String] path the path to the directory to make
+    # @param [Int] mode the permissions to set on the new directory
+    #
+    # @return [Bool] if the directory was created
+    def mkdir_p(path, mode = 0o600)
+      super(path, mode)
+    end
+
+    # Remove a directory
+    #
+    # @param [String] path the path to the file
+    # @param [Bool] force Whether or not to throw an exception if the operation
+    #                     fails
+    #
+    # @raise [Error] if force=false
+    #
+    # @return [Bool] if or if not the method succeeded
+    def rmdir(path, force = false)
+      force_remove(force) { super(path) }
+    end
+
+    # Remove a directory recursively
+    #
+    # @param [String] path the path to the file
+    # @param [Bool] force Whether or not to throw an exception if the directory
+    #                     doesn't exist.
+    #
+    # @raise [Error] if force=false
+    #
+    # @return [Bool] if or if not the method succeeded
+    def rmdirs(path, force = false)
+      force_remove(force) { super(path) }
+    end
+
+    # Recursively remove directories and files.
+    #
+    # @param [String] path the path to the file
+    # @param [Bool] force Whether or not to throw an exception if the directory
+    #                     doesn't exist.
+    #
+    # @raise [Error] if force=false
+    #
+    # @return [Bool] if or if not the method succeeded
+    def rm_rf(path, force = false)
+      force_remove(force) do
+        return remove(path) if file?(path)
+        readdir(path) do |f|
+          fpath = ::File.join(path, f.filename)
+          rm_rf(fpath) if directory?(fpath)
+          remove(fpath) if file?(fpath)
+        end
+        rmdir(path)
+      end
+    end
+
+    # Read from a file and return the data
+    #
+    # @param [String] path the path to the file
+    # @param [Int] len the number of bytes to read
+    #
+    # @return [String] the data from the file
+    def read(path, len = nil)
+      open(path, 'r') { |f| f.read(len) }
+    end
+
+    # Write to a file
+    #
+    # @param [String] path the path to the file
+    # @param [String] data the data to be written
+    #
+    # @return [String] the number of bytes written
+    def write(path, data)
+      open(path, 'w') { |f| f.write(data) }
+    end
+
+    # Read from a directory, optionally outputting a list of Attr
+    # objects or yielding to a block
+    #
+    # @example Usage with a block:
+    #   client.readdir('/') do |paths|
+    #     puts paths.filename
+    #   end
+    #
+    # @example Usage without a block:
+    #   client.readdir('/').each do |paths|
+    #     puts paths.filename
+    #   end
+    #
+    # @param [String] path the path to read from
+    #
+    # @return [Array<Attr>] a list of Attr objects
+    #
+    # @yield [Attr] Attr objects
+    def readdir(path)
+      attrs = []
+      super(path) do |attr|
+        unless current_or_previous_dir?(attr.filename)
+          block_given? ? yield(attr) : attrs.push(attr)
+        end
+      end
+
+      return attrs unless block_given?
+    end
+
+    # Change the permissions of a file or directory
+    #
+    # @param [String] path Path to the file to chmod
+    # @param [Int] mode_int The permissions to set
+    # @option options [Bool] :recursive Set to recursively chmod the directory
+    def chmod(path, mode_int, options = {})
+      return chmod_r(path, mode_int) if options[:recursive]
+      super(path, mode_int)
+    end
+
+    # Get an Attr object for the file at the specified path
+    #
+    # Note that this method will cache it's result for a specific file for the
+    # entire lifetime of a Client object.  If you need to get an updated Attr
+    # for a file/directory, you need to create a new Client.
+    #
+    # @param [String] path The path to the file or directory to stat
+    # @param options [Bool] :refresh If this is set, the file will be opened
+    # and reopened to guarantee stat returns updated values
+    #
+    # @return [Attr] An attr object
+    def stat(path, options = {})
+      # close the file and repoen it guarantee that the newest data is present
+      # opening in a block will guarantee it is closed
+      open(path, 'w') { } if options[:refresh]
+
+      super(path)
+    end
+
+    # Move a file to a new path.
+    #
+    # @param [String] old The path to the file to move
+    # @param [String] new The new destination
+    def move(old, new)
+      rename(old, new)
+    end
+
+    # Change the current working directory
+    #
+    # @param [String] path The directory to change to
+    def cd(path)
+      super(path)
+    end
+
+    # Set the current working directory
+    #
+    # @param [String] path The directory to change to
+    def setwd(path)
+      super(path)
+    end
+
+    # Return the current working directory
+    #
+    # @param [Int] len The length of the buffer that should be allocated
+    #                  to store the cwd.  An exception will be thrown if it
+    #                  is too small.
+    #
+    # @return [String] The current working directory
+    def cwd
+      super
+    end
+
+    private
+
+    # Return if the specified string is the path to the current
+    # directory '.' or to the previous directory '..'
+    def current_or_previous_dir?(name)
+      case name
+      when '.', '..'
+        true
+      else
+        false
+      end
+    end
+
+    # If force is true, call the block and just return zero if it
+    # throws an exception
+    def force_remove(force)
+      return yield unless force
+      begin
+        return yield
+      rescue Errno::ENOENT
+        return 0
+      end
+    end
+
+    # Maps mode strings to oflags
+    MODE_STR_TO_FLAGS = {
+      'r' => Qfs::O_RDONLY,
+      'w' => Qfs::O_WRONLY | Qfs::O_TRUNC | Qfs::O_CREAT,
+      'a' => Qfs::O_WRONLY,
+    }
+
+    ##
+    # Convert the mode strings to oflags
+    def mode_to_flags(mode)
+      MODE_STR_TO_FLAGS[mode]
+    end
+  end
+
+  ##
+  # A File on QFS.
+  class File
+    # Read from a file.  Don't specify a length to read the entire file.
+    #
+    # @param [Int] len the number of bytes to read. Omit or set to nil to
+    # read the entire file.
+    #
+    # @return [String] the data read from the file.
+    def read(len = nil)
+      len ||= stat.size
+      read_len(len)
+    end
+
+    # Seek to the specified position in the file.  The default 'whence' value
+    # is SEEK_CUR, so the offset will be applied to the current file position.
+    #
+    # @param [Int] offset The offset to seek to
+    # @param [Int] whence One of the following constants: IO::SEEK_CUR,
+    # IO::SEEK_END, IO::SEEK_SET.  Defaults to IO::SEEK_CUR
+    #
+    # @return [Int] The current file position
+    def seek(offset, whence=IO::SEEK_CUR)
+      seek_internal(offset, whence)
+    end
+  end
+
+  # A container class for the properties of a file or directory.
+  # These can be retrieved with either Client::stat or File#stat.
+  #
+  # @attr_reader [String] filename The base name of the file/directory
+  # @attr_reader [Int] id
+  # @attr_reader [Int] mode The permissions set on the file/directory
+  # @attr_reader [Int] uid User ID
+  # @attr_reader [Int] gid Group ID
+  # @attr_reader [Time] mtime The time last modified
+  # @attr_reader [Time] ctime The time the file/directory's attributes were
+  #                           changed
+  # @attr_reader [Bool] directory If the file is a directory
+  # @attr_reader [Int] size The size of the file
+  # @attr_reader [Int] chunks The number of chunks in the file or files in a
+  #                           directory
+  # @attr_reader [Int] directories The number of subdirectories
+  # @attr_reader [Int] replicas
+  # @attr_reader [Int] stripes
+  # @attr_reader [Int] recovery_stripes
+  # @attr_reader [Int] striper_type
+  # @attr_reader [Int] stripe_size
+  # @attr_reader [Int] min_stier
+  # @attr_reader [Int] max_stier
+  class Attr
+    # Attempt to mimic the format of the QFS "ls" command
+    def to_s
+      [
+        "#{directory? ? 'd' : '-'}#{mode_to_s}",
+        '-',
+        uid,
+        gid,
+        size,
+        mtime.strftime('%Y-%m-%d %H:%M'),
+        filename,
+      ].join(' ')
+    end
+
+    private
+
+    ##
+    # Get the mode as a typically formatted string
+    # returns a string in the form 'rwxrwxrwx'
+    def mode_to_s
+      m = mode
+      perms = %w(x w r)
+      8.downto(0).reduce('') do |sum, i|
+        sum + ((m & (1 << i)) != 0 ? perms[i % perms.length] : '-')
+      end
+    end
+  end
+end