Migrated README to README.md for Markdown rendering on GitHub.

2 files changed, 100 insertions, 379 deletions

diff --git a/README b/README
index 398dd65..5efad5c 100644
--- a/README
+++ b/README
@@ -1,380 +1,3 @@
-General Information
-===================
+Please look at README.md
 
-FUSE (Filesystem in Userspace) is a simple interface for userspace
-programs to export a virtual filesystem to the Linux kernel.  FUSE
-also aims to provide a secure method for non privileged users to
-create and mount their own filesystem implementations.
-
-You can download the source code releases from
-
-  http://sourceforge.net/projects/fuse
-
-or alternatively you can use CVS to get the very latest development
-version:
-
-  cvs -d :pserver:anonymous@fuse.cvs.sourceforge.net:/cvsroot/fuse co fuse
-
-
-Dependencies
-============
-
-Linux kernel version 2.6.X where X >= 9.
-
-Alternatively a kernel module from FUSE release 2.5.* can be used with
-this release, which supports kernels >= 2.4.21.
-
-Installation
-============
-
-./configure
-make
-make install
-modprobe fuse
-
-You may also need to add '/usr/local/lib' to '/etc/ld.so.conf' and/or
-run ldconfig.
-
-You'll also need a fuse kernel module, Linux kernels 2.6.14 or later
-contain FUSE support.
-
-For more details see the file 'INSTALL'
-
-How To Use
-==========
-
-FUSE is made up of three main parts:
-
- - A kernel filesystem module
-
- - A userspace library
-
- - A mount/unmount program
-
-
-Here's how to create your very own virtual filesystem in five easy
-steps (after installing FUSE):
-
-  1) Edit the file example/fusexmp.c to do whatever you want...
-
-  2) Build the fusexmp program
-
-  3) run 'example/fusexmp /mnt/fuse -d'
-
-  4) ls -al /mnt/fuse
-
-  5) Be glad
-
-If it doesn't work out, please ask!  Also see the file 'include/fuse.h' for
-detailed documentation of the library interface.
-
-Security
-========
-
-If you run 'make install', the fusermount program is installed
-set-user-id to root.  This is done to allow normal users to mount
-their own filesystem implementations.
-
-There must however be some limitations, in order to prevent Bad User from
-doing nasty things.  Currently those limitations are:
-
-  - The user can only mount on a mountpoint, for which it has write
-    permission
-
-  - The mountpoint is not a sticky directory which isn't owned by the
-    user (like /tmp usually is)
-
-  - No other user (including root) can access the contents of the mounted
-    filesystem.
-
-Configuration
-=============
-
-Some options regarding mount policy can be set in the file
-'/etc/fuse.conf'
-
-Currently these options are:
-
-mount_max = NNN
-
-  Set the maximum number of FUSE mounts allowed to non-root users.
-  The default is 1000.
-
-user_allow_other
-
-  Allow non-root users to specify the 'allow_other' or 'allow_root'
-  mount options.
-
-
-Mount options
-=============
-
-Most of the generic mount options described in 'man mount' are
-supported (ro, rw, suid, nosuid, dev, nodev, exec, noexec, atime,
-noatime, sync async, dirsync).  Filesystems are mounted with
-'-onodev,nosuid' by default, which can only be overridden by a
-privileged user.
-
-These are FUSE specific mount options that can be specified for all
-filesystems:
-
-default_permissions
-
-  By default FUSE doesn't check file access permissions, the
-  filesystem is free to implement it's access policy or leave it to
-  the underlying file access mechanism (e.g. in case of network
-  filesystems).  This option enables permission checking, restricting
-  access based on file mode.  This is option is usually useful
-  together with the 'allow_other' mount option.
-
-allow_other
-
-  This option overrides the security measure restricting file access
-  to the user mounting the filesystem.  So all users (including root)
-  can access the files.  This option is by default only allowed to
-  root, but this restriction can be removed with a configuration
-  option described in the previous section.
-
-allow_root
-
-  This option is similar to 'allow_other' but file access is limited
-  to the user mounting the filesystem and root.  This option and
-  'allow_other' are mutually exclusive.
-
-kernel_cache
-
-  This option disables flushing the cache of the file contents on
-  every open().  This should only be enabled on filesystems, where the
-  file data is never changed externally (not through the mounted FUSE
-  filesystem).  Thus it is not suitable for network filesystems and
-  other "intermediate" filesystems.
-
-  NOTE: if this option is not specified (and neither 'direct_io') data
-  is still cached after the open(), so a read() system call will not
-  always initiate a read operation.
-
-auto_cache
-
-  This option enables automatic flushing of the data cache on open().
-  The cache will only be flushed if the modification time or the size
-  of the file has changed.
-
-large_read
-
-  Issue large read requests.  This can improve performance for some
-  filesystems, but can also degrade performance.  This option is only
-  useful on 2.4.X kernels, as on 2.6 kernels requests size is
-  automatically determined for optimum performance.
-
-direct_io
-
-  This option disables the use of page cache (file content cache) in
-  the kernel for this filesystem.  This has several affects:
-
-     - Each read() or write() system call will initiate one or more
-       read or write operations, data will not be cached in the
-       kernel.
-
-     - The return value of the read() and write() system calls will
-       correspond to the return values of the read and write
-       operations.  This is useful for example if the file size is not
-       known in advance (before reading it).
-
-max_read=N
-
-  With this option the maximum size of read operations can be set.
-  The default is infinite.  Note that the size of read requests is
-  limited anyway to 32 pages (which is 128kbyte on i386).
-
-max_readahead=N
-
-  Set the maximum number of bytes to read-ahead.  The default is
-  determined by the kernel.  On linux-2.6.22 or earlier it's 131072
-  (128kbytes)
-
-max_write=N
-
-  Set the maximum number of bytes in a single write operation.  The
-  default is 128kbytes.  Note, that due to various limitations, the
-  size of write requests can be much smaller (4kbytes).  This
-  limitation will be removed in the future.
-
-async_read
-
-  Perform reads asynchronously. This is the default
-
-sync_read
-
-  Perform all reads (even read-ahead) synchronously.
-
-hard_remove
-
-  The default behavior is that if an open file is deleted, the file is
-  renamed to a hidden file (.fuse_hiddenXXX), and only removed when
-  the file is finally released.  This relieves the filesystem
-  implementation of having to deal with this problem.  This option
-  disables the hiding behavior, and files are removed immediately in
-  an unlink operation (or in a rename operation which overwrites an
-  existing file).
-
-  It is recommended that you not use the hard_remove option. When
-  hard_remove is set, the following libc functions fail on unlinked
-  files (returning errno of ENOENT):
-     - read()
-     - write()
-     - fsync()
-     - close()
-     - f*xattr()
-     - ftruncate()
-     - fstat()
-     - fchmod()
-     - fchown()
-
-debug
-
-  Turns on debug information printing by the library.
-
-fsname=NAME
-
-  Sets the filesystem source (first field in /etc/mtab).  The default
-  is the program name.
-
-subtype=TYPE
-
-  Sets the filesystem type (third field in /etc/mtab).  The default is
-  the program name.
-
-  If the kernel suppports it, /etc/mtab and /proc/mounts will show the
-  filesystem type as "fuse.TYPE"
-
-  If the kernel doesn't support subtypes, the source filed will be
-  "TYPE#NAME", or if fsname option is not specified, just "TYPE".
-
-use_ino
-
-  Honor the 'st_ino' field in getattr() and fill_dir().  This value is
-  used to fill in the 'st_ino' field in the stat()/lstat()/fstat()
-  functions and the 'd_ino' field in the readdir() function.  The
-  filesystem does not have to guarantee uniqueness, however some
-  applications rely on this value being unique for the whole
-  filesystem.
-
-readdir_ino
-
-  If 'use_ino' option is not given, still try to fill in the 'd_ino'
-  field in readdir().  If the name was previously looked up, and is
-  still in the cache, the inode number found there will be used.
-  Otherwise it will be set to '-1'.  If 'use_ino' option is given,
-  this option is ignored.
-
-nonempty
-
-  Allows mounts over a non-empty file or directory.  By default these
-  mounts are rejected (from version 2.3.1) to prevent accidental
-  covering up of data, which could for example prevent automatic
-  backup.
-
-umask=M
-
-  Override the permission bits in 'st_mode' set by the filesystem.
-  The resulting permission bits are the ones missing from the given
-  umask value.  The value is given in octal representation.
-
-uid=N
-
-  Override the 'st_uid' field set by the filesystem.
-
-gid=N
-
-  Override the 'st_gid' field set by the filesystem.
-
-blkdev
-
-  Mount a filesystem backed by a block device.  This is a privileged
-  option.  The device must be specified with the 'fsname=NAME' option.
-
-entry_timeout=T
-
-  The timeout in seconds for which name lookups will be cached. The
-  default is 1.0 second.  For all the timeout options, it is possible
-  to give fractions of a second as well (e.g. "-oentry_timeout=2.8")
-
-negative_timeout=T
-
-  The timeout in seconds for which a negative lookup will be cached.
-  This means, that if file did not exist (lookup retuned ENOENT), the
-  lookup will only be redone after the timeout, and the file/directory
-  will be assumed to not exist until then.  The default is 0.0 second,
-  meaning that caching negative lookups are disabled.
-
-attr_timeout=T
-
-  The timeout in seconds for which file/directory attributes are
-  cached.  The default is 1.0 second.
-
-ac_attr_timeout=T
-
-  The timeout in seconds for which file attributes are cached for the
-  purpose of checking if "auto_cache" should flush the file data on
-  open.   The default is the value of 'attr_timeout'
-
-intr
-
-  Allow requests to be interrupted.  Turning on this option may result
-  in unexpected behavior, if the filesystem does not support request
-  interruption.
-
-intr_signal=NUM
-
-  Specify which signal number to send to the filesystem when a request
-  is interrupted.  The default is 10 (USR1).
-
-modules=M1[:M2...]
-
-  Add modules to the filesystem stack.  Modules are pushed in the
-  order they are specified, with the original filesystem being on the
-  bottom of the stack.
-
-
-Modules distributed with fuse
------------------------------
-
-iconv
-`````
-Perform file name character set conversion.  Options are:
-
-from_code=CHARSET
-
-  Character set to convert from (see iconv -l for a list of possible
-  values).  Default is UTF-8.
-
-to_code=CHARSET
-
-  Character set to convert to.  Default is determined by the current
-  locale.
-
-
-subdir
-``````
-Prepend a given directory to each path. Options are:
-
-subdir=DIR
-
-  Directory to prepend to all paths.  This option is mandatory.
-
-rellinks
-
-  Transform absolute symlinks into relative
-
-norellinks
-
-  Do not transform absolute symlinks into relative.  This is the default.
-
-
-Reporting bugs
-==============
-
-Please send bug reports to the <fuse-devel@lists.sourceforge.net>
-mailing list.
-
-The list is open, you need not be subscribed to post.
+This file just exists to make automake happy.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ef3b5a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+libfuse
+=======
+
+About
+-----
+
+FUSE (Filesystem in Userspace) is an interface for userspace programs
+to export a filesystem to the Linux kernel. The FUSE project consists
+of two components: the *fuse* kernel module (maintained in the regular
+kernel repositories) and the *libfuse* userspace library (maintained
+in this repository). libfuse provides the reference implementation
+for communicating with the FUSE kernel module.
+
+A FUSE file system is typically implemented as a standalone
+application that links with libfuse. libfuse provides functions to
+mount the file system, unmount it, read requests from the kernel, and
+send responses back. libfuse offers two APIs: a "high-level",
+synchronous API, and a "low-level" asynchronous API. In both cases,
+incoming requests from the kernel are passed to the main program using
+callbacks. When using the high-level API, the callbacks may work with
+file names and paths instead of inodes, and processing of a request
+finishes when the callback function returns. When using the low-level
+API, the callbacks must work with inodes and responses must be sent
+explicitly using a separate set of API functions.
+
+
+Installation
+------------
+
+    ./configure
+    make -j8
+    make install
+
+You may also need to add `/usr/local/lib` to `/etc/ld.so.conf` and/or
+run *ldconfig*. If you're building from the git repository (instead of
+using a release tarball), you also need to run `./makeconf.sh` to
+create the `configure` script.
+
+You'll also need a fuse kernel module (Linux kernels 2.6.14 or later
+contain FUSE support).
+
+For more details see the file `INSTALL`
+
+Security implications
+---------------------
+
+If you run `make install`, the *fusermount* program is installed
+set-user-id to root.  This is done to allow normal users to mount
+their own filesystem implementations.
+
+There must however be some limitations, in order to prevent Bad User from
+doing nasty things.  Currently those limitations are:
+
+  - The user can only mount on a mountpoint, for which it has write
+    permission
+
+  - The mountpoint is not a sticky directory which isn't owned by the
+    user (like /tmp usually is)
+
+  - No other user (including root) can access the contents of the mounted
+    filesystem (though this can be relaxed)
+
+
+Building your own filesystem
+------------------------------
+
+FUSE comes with several example file systems in the `examples`
+directory. For example, the *fusexmp* example mirrors the contents of
+the root directory under the mountpoint. Start from there and adapt
+the code!
+
+The documentation of the API functions and necessary callbacks is
+mostly contained in the files `include/fuse.h` (for the high-level
+API) and `include/fuse_lowlevel.h` (for the low-level API).
+
+
+Getting Help
+------------
+
+If you need help, please ask on the <fuse-devel@lists.sourceforge.net>
+mailing list (subscribe at
+https://lists.sourceforge.net/lists/listinfo/fuse-devel).
+
+Please report any bugs on the GitHub issue tracker at
+https://github.com/libfuse/main/issues.
+
+
+Credits
+-------
+
+libfuse is currently maintained by Nikolaus Rath.
+
+The CUSE feature was added by Tejun Heo.
+
+FUSE (both libfuse and the kernel module) was written by Miklos
+Szeredi.
+
+