Permalink
Browse files

first commit

  • Loading branch information...
1 parent e43d36e commit 9c5307eb4d94150cefdef51bb928b992d7aa653c @fizx committed Sep 18, 2009
Showing with 3,182 additions and 41 deletions.
  1. +1 −1 .gitignore
  2. +279 −0 API.txt
  3. +63 −0 Changes.txt
  4. +17 −17 LICENSE
  5. +56 −0 README
  6. +0 −18 README.rdoc
  7. +2 −4 Rakefile
  8. +11 −0 TODO
  9. +1 −1 VERSION
  10. +4 −0 ext/MANIFEST
  11. +157 −0 ext/Makefile
  12. +7 −0 ext/extconf.rb
  13. +177 −0 ext/fusefs_fuse.c
  14. +17 −0 ext/fusefs_fuse.h
  15. BIN ext/fusefs_fuse.o
  16. BIN ext/fusefs_lib.bundle
  17. +1,528 −0 ext/fusefs_lib.c
  18. BIN ext/fusefs_lib.o
  19. +12 −0 ext/mkmf.log
  20. +223 −0 lib/fusefs.rb
  21. +94 −0 sample/demo.rb
  22. +83 −0 sample/dictfs.rb
  23. +21 −0 sample/hello.rb
  24. +54 −0 sample/openurifs.rb
  25. +77 −0 sample/railsfs.rb
  26. +134 −0 sample/sqlfs.rb
  27. +164 −0 sample/yamlfs.rb
View
@@ -2,4 +2,4 @@
.DS_Store
coverage
rdoc
-pkg
+pkg
View
279 API.txt
@@ -0,0 +1,279 @@
+FuseFS API DOCUMENT
+===================
+
+Last updated: 2005.09.19 by Greg Millam
+
+WARNING
+-------
+
+Note: If you use DirLink (in demo.rb) or in any way access a FuseFS filesystem
+from *within* the ruby script accessing the FuseFS, then FuseFS will hang, and
+the only recourse is a kill -KILL.
+
+Also: If there are any open files or shells with 'pwd's in your filesystem
+when you exit your ruby script, fuse *might* not actually be unmounted. To
+unmount a path yourself, run the command:
+
+ fusermount -u <path>
+
+to unmount any FUSE filesystems mounted at <path>.
+
+
+FuseFS API
+----------
+
+
+FuseFS provides a layer of abstraction to a programmer who wants to create a
+virtual filesystem via FUSE.
+
+FuseFS programs consist of two parts:
+
+1) FuseFS, which is defined in 'fusefs.rb'
+2) An object that defines a virtual directory. This must define a number of
+ methods (given below, in "Directory Methods" section) in order to be
+ usable.
+
+To write a FuseFS program, you must:
+
+* Define and create a Directory object that responds to the methods required
+ by FuseFS for its desired use.
+
+* Call FuseFS.set_root <virtualdir> with the object defining your virtual
+ directory.
+
+* Mount FuseFS under a real directory on your filesystem.
+
+* Call FuseFS.run to start receiving and executing events.
+
+Happy Filesystem Hacking!
+
+
+Hello World FS
+--------------
+helloworld.rb
+
+This creates a filesystem that contains exactly 1 file: "hello.txt" that, when
+read, returns "Hello, World!"
+
+This is not writable to, and contains no other files.
+
+ require 'fusefs'
+
+ class HelloDir
+ def contents(path)
+ ['hello.txt']
+ end
+ def file?(path)
+ path -- '/hello.txt'
+ end
+ def read_file(path)
+ "Hello, World!\n"
+ end
+ end
+
+ hellodir = HelloDir.new
+ FuseFS.set_root( hellodir )
+
+ # Mount under a directory given on the command line.
+ FuseFS.mount_under ARGV.shift
+ FuseFS.run
+
+
+Directory Methods
+-----------------
+
+Without any methods defined, any object is by default a content-less,
+file-less directory.
+
+The following are necessary for most or all filesystems:
+
+ Directory listing and file type methods:
+
+ :contents(path) # Return an array of file and dirnames within <path>.
+ :directory?(path) # Return true if <path> is a directory.
+ :file?(path) # Return true if <path> is a file (not a directory).
+ :executable?(path) # Return true if <path> is an executable file.
+ :size(path) # Return the file size. Necessary for apache, xmms,
+ etc.
+
+ File reading:
+
+ :read_file(path) # Return the contents of the file at location <path>.
+
+The following are only necessary if you want a filesystem that can be modified
+by the user. Without defining any of the below, the contents of the filesystem
+are automatically read-only.
+
+ File manipulation:
+
+ :can_write?(path) # Return true if the user can write to file at <path>.
+ :write_to(path,str) # Write the contents of <str> to file at <path>.
+
+ :can_delete?(path) # Return true if the user can delete file at <path>.
+ :delete(path) # Delete the file at <path>
+
+ Directory manipulation:
+
+ :can_mkdir?(path) # Return true if user can make a directory at <path>.
+ :mkdir(path) # Make a directory at path.
+
+ :can_rmdir?(path) # Return true if user can remove directory at <path>.
+ :rmdir(path) # Remove it.
+
+ Neat "toy":
+
+ :touch(path) # Called when a file is 'touch'd or otherwise has
+ their timestamps explicitly modified. I envision
+ this as a neat toy, maybe you can use it for a
+ push-button file?
+ "touch button" -> unmounts fusefs?
+ "touch musicfile.mp3" -> Play the mp3.
+
+If you want a lower level control of your file, then you can use:
+
+ :raw_open(path,mode) # mode is "r" "w" or "rw", with "a" if the file
+ is opened for append. If raw_open returns true,
+ then the following calls are made:
+ :raw_read(path,off,sz) # Read sz bites from file at path starting at
+ offset off
+ :raw_write(path,off,sz,buf) # Write sz bites of buf to path starting at
+ offset off
+ :raw_close(path) # Close the file.
+
+
+Method call flow
+================
+
+List contents:
+ :directory? will be checked before :contents
+ (Most 'ls' or 'dir' functions will go on next
+ to getattr() for all contents)
+
+Read file:
+ :file? will be checked before :read_file
+
+Getattr
+ :directory? will be checked first.
+
+ :file? will be checked before :can_write?
+ :file? will be checked before :executable?
+
+Writing files:
+ * directory? is usually called on the directory
+ The FS wants to write a new file to, before this
+ can occur.
+ :can_write? will be checked before :write_to
+
+Deleting files:
+ :file? will be checked before :can_delete?
+ :can_delete? will be checked before :delete
+
+Creating dirs:
+ * directory? is usually called on the directory
+ The FS wants to make a new directory in, before
+ this can occur.
+ :directory? will be checked.
+ :can_mkdir? is called only if :directory? is false.
+ :can_mkdir? will be checked before :mkdir
+
+Deleting dirs:
+ :directory? will be checked before :can_rmdir?
+ :can_rmdir? will be checked before :rmdir
+
+
+module FuseFS
+-------------
+
+FuseFS methods:
+
+ FuseFS.set_root(object)
+ Set the root virtual directory to <object>. All queries for obtaining
+ file information is directed at object.
+
+ FuseFS.mount_under(path[,opt[,opt,...]])
+ This will cause FuseFS to virtually mount itself under the given path.
+ 'path' is required to be a valid directory in your actual filesystem.
+
+ 'opt's are FUSE options. Most likely, you will only want 'allow_other'
+ or 'allow_root'. The two are mutually exclusive in FUSE, but allow_other
+ will let other users, including root, access your filesystem. allow_root
+ will only allow root to access it.
+
+ Also available for FuseFS users are:
+ default_permissions, max_read=N, fsname=NAME.
+
+ For more information, look at FUSE.
+
+ (P.S: I know FUSE allows other options, but I don't think any of the
+ rest will do any good with FuseFS. If you think otherwise, please let me
+ know!)
+
+ FuseFS.run
+ This is the final step to make your virtual filesystem accessible. It is
+ recommended you run this as your main thread, but you can thread off to
+ run this.
+
+ FuseFS.handle_editor = bool (true by default)
+ If handle_editor is true, then FuseFS will attempt to capture all editor
+ files and prevent them from being passed to FuseRoot. It also prevents
+ created and unmodified files from being passed as well, as vim (among
+ others) will attempt to create and then remove a file that does not
+ exist.
+
+ FuseFS.reader_uid and FuseFS.reader_gid
+ When the filesystem is accessed, the accessor's uid or gid is returned
+ by FuseFS.reader_uid and FuseFS.reader_gid. You can use this in
+ determining your permissions, or even provide different files for
+ different users!
+
+ FuseFS.fuse_fd and FuseFS.process
+ These are not intended for use by the programmer. If you want to muck
+ with this, read the code to see what they do :D.
+
+
+
+FuseDir
+----------
+
+FuseFS::FuseDir defines the methods "split_path" and "scan_path". You
+should typically inherit from FuseDir in your own directory objects.
+
+ base, rest = split_path(path) # base is the file or directory in the
+ current context. rest is either nil,
+ or a path that is requested. If 'rest'
+ exists, then you should recurse the paths.
+ base, *rest = scan_path(path) # scan_path returns an array of all
+ directory and file elements given by
+ <path>. This is useful when you're
+ encapsulating an entire fs into one
+ object.
+
+MetaDir
+-------
+
+MetaDir is a full filesystem defined with hashes. It is writable, and the user
+can create and edit files within it, as well as the programmer.
+
+Usage:
+ root = MetaDir.new
+
+ root.mkdir("/hello")
+ root.write_to("/hello/world","Hello, World!\n")
+ root.write_to("/hello/everybody","Hello, Everybody!\n")
+
+ FuseFS.set_root(root)
+
+Because MetaDir is fully recursive, you can mount your own or other defined
+directory structures under it. For example, to mount a dictionary filesystem
+(as demonstrated in samples/dictfs.rb), use:
+
+ root.mkdir("/dict",DictFS.new)
+
+Conclusion
+----------
+
+Happy Hacking! If you do anything neat with this, please let me know!
+
+My email address is walker@deafcode.com
+
+Thanks for using FuseFS!
View
@@ -0,0 +1,63 @@
+FuseFS 0.7
+==========
+
+ * It's now a Rubygem on Github
+
+FuseFS 0.6
+==========
+
+ * FuseFS.mount_under() now takes FUSE options as optional arguments, such as
+ 'allow_other' and 'allow_root'
+ * rmdir now works. (Whoops!)
+
+FuseFS 0.5.1
+============
+
+ * Bugfix for dealing with raw files (Thanks, Kent Sibilev)
+
+FuseFS 0.5
+==========
+
+ * Fixed for FUSE 2.4. direct_io turned from a mount option in 2.3 to a lib
+ option in 2.4.
+ * _why_the_lucky_stiff's railsfs.rb added to the samples/ dir.
+ * FuseRoot#raw_open is called with the path and "r" "w" "rw" for read or
+ write modes, along with "a" if it is called for appending.
+ * If raw_open returns true, FuseFS will call raw_read, raw_write, and
+ raw_close at necessary points. (See API.txt)
+ * FuseRoot#size is optionally called to determine file sizes, should the
+ user want a file size to be reported as anything other than 0.
+
+FuseFS 0.4
+==========
+
+ * Stronger and more robust handling of editor swap files, but still
+ incomplete.
+ * Peppered with debug statements.
+ * A bit cleaner method of calling ruby functions.
+ * rf_rename fixed. Whoops!
+
+FuseFS 0.3
+==========
+
+ * read_file borked FuseFS when a binary file was returned. Instead of using
+ strdup, it now mallocs according to the returned size, as appropriate.
+ * Addition of sample/openurifs.rb
+ * 'touch file' emptied a file, since it opened and then released without
+ writing. I added a 'modified' flag to fix this.
+ * 'touch' method call added, and called when a program attempts to modify
+ a file's time.
+ * 'executable?' check added in case programmer wants to the file to report
+ itself as executable to the filesystem.
+ * vim and emacs swap files are not passed to FuseFS =).
+
+FuseFS 0.2
+==========
+
+ * Fix call for deleting files from 'remove' to 'delete' to match API spec.
+ * Addition of sample/yamlfs.rb
+
+FuseFS 0.1
+==========
+
+ Initial import.
View
34 LICENSE
@@ -1,20 +1,20 @@
-Copyright (c) 2009 Kyle Maxwell
+Copyright (c) 2005 Greg Millam.
+Copyright (c) 2009 Kyle Maxwell.
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
Oops, something went wrong.

0 comments on commit 9c5307e

Please sign in to comment.