
INTRODUCTION
============

The ntfs-3g driver is an open source, GPL licensed, third generation Linux 
NTFS driver which was implemented by the Linux-NTFS project. It provides 
full read-write access to NTFS, excluding access to encrypted files, writing 
compressed files, changing file ownerships and access rights.

Technically it's based on and a major improvement to ntfsmount. The improvements 
include functionality, reliability, quality and performance enhancements. 

The driver currently is in BETA status: before release of this software we 
haven't experienced any driver crashes or data loss during our heavy quality 
testing, however we are aware of some minor issues which will be resolved
in the near future. We listed all of them in a below section. Please report 
any new problem to linux-ntfs-dev@lists.sourceforge.net if it's not listed 
yet in the latest release of this software. 


QUICK INSTALLATION
==================
	
Make sure you have the basic Linux development tools and the full FUSE 
package (http://fuse.sourceforge.net) is already installed correctly on 
the computer. Then type:  

	./configure
	make
	make install      # or 'sudo make install' if you aren't root.


USAGE
=====

If there was no error during installation then you can mount an NTFS volume 
read-write for everybody (unmount the volume if it was already mounted, 
replace the 'device' and the 'mount point' below, if needed)

    ntfs-3g /dev/hda1 /mnt/windows

You may also need to set the 'locale' option to make all files with national 
characters visible. Replace the below hu_HU.utf8 with the appropriate setting. 

    ntfs-3g /dev/hda1 /mnt/windows -o locale=hu_HU.utf8

Please see the ntfs-3g manual page for more options and examples.

You can also make NTFS to be mounted during boot by putting the below 
line into /etc/fstab 

    /dev/hda1 /mnt/windows ntfs-3g defaults 0 0


PERFORMANCE
===========

Our highest priority is reliable functionality, performance comes only 
next. However acceptable performance is part of the functionality so we 
constantly keep an eye on it and consider any major performance issue to 
be a real functionality problem as well.

Below are the averaged file creation, deletion and access performance 
numbers got by running 'bonnie++ -s0' using several filesystems (the 
benchmark used 16,000 files per directory in each sessions):

Version  1.03    ------Sequential Create------ --------Random Create--------
                 -Create-- --Read--- -Delete-- -Create-- --Read--- -Delete--
           files  /sec %CP  /sec %CP  /sec %CP  /sec %CP  /sec %CP  /sec %CP
reiserfs     16k 21459  99 +++++ +++ 17856  96 20172  98 +++++ +++ 16414  96
jfs          16k  7015  13 +++++ +++  5868  10  3068  14 +++++ +++  1075   3
ntfs-3g      16k  3021  99 14291  99  5226  99  3548  99 16149  99  5223  99
xfs          16k  2401  17 +++++ +++  2095  15  2301  20 +++++ +++   347   2
ext3         16k  1862  96 +++++ +++ +++++ +++  1914  96 +++++ +++  9695  98
minix        16k  1450  97 +++++ +++ 18148  94  1694  97 +++++ +++  4847  98
fat32        16k   366  97 +++++ +++  1809  97   428  97 +++++ +++  1361  97
paragon ntfs 16k    58  98  1259  99   245  99    55  99 +++++ +++   832  99
captive ntfs    Always crashes early on file creations and loses files.
	        This was also confirmed and fix denied by its developer.

We estimate the ntfs-3g driver performance could be increased by several 
times.


KNOWN ISSUES, TROUBLESHOOTING
=============================

Recently added or updated items are always on the top.


Problem:    Deleting files don't free disk space.
Answer:     In all investigated cases ntfs-3g accounted free space correctly.
            Below are the reasons why disk space isn't always freed:
	      A) In certain cases, the files aren't deleted in real but 
                 moved to a 'Trash' directory. If the 'Trash' directory is
                 emptied then the disk space is reclaimed. 
	      B) By design, Linux and Unixes free the disk space of deleted 
                 files permanently only if no software is using them anymore. 
	      C) NTFS is able to store small files and directories in fixed
                 size (1 kB) MFT records (inodes). When such files are delete
                 then the MFT records are marked free for reuse or undelete, 
                 and no space can be freed. 
Status:     Not a driver problem.


Problem:    File modification times aren't always updated.
Status:     High priority work.


Problem:    VMware segfaults during startup.
Answer:     By default VMware tries to use shared writable mmap for paging 
            files but it can't detect that it's not yet supported. 
Workaround: Set "mainMem.useNamedFile=FALSE" in the .vmx file. That will
	    disable these paging files and VMware will work fine.
Status:     Priority, hard work.


Problem:    Writing large files sometimes can be very slow.
Answer:     The cluster allocator and the mapping pairs updater algorithms 
	    aren't efficient for large files on very fragmented volumes.
Workaround: Try to defragment NTFS, it may help.
Status:     Priority work.


Problem:    Why doesn't the driver work on 64-bit and big-endian systems?
Answer:     The code is 64-bit ready and almost fully endian safe, however
            unfortunately we are unable to validate the functionality and 
            keep ensuring correctness for the future due to lack of target 
            hardwares.  


Problem:    "File exists" message when deleting "empty" directories: 
Answer:     If 'locale' isn't set correctly then glibc can't convert
	    some filenames, so they aren't visible and the directory 
	    indeed isn't empty. Occurs very rarely.
Workaround: Set your 'locale' properly according to the used characters.
Status:     High priority work.


Problem:    "Operation not supported" message when creating a file:
Answer:     This is a controlled refusal of file creation which can happen 
            when there are already about 100,000 files on the NTFS and the
            MFT needs to be extended in a way which isn't implemented yet.
Workaround: Delete files then you can create new ones.
Status:     High priority work.


Problem:    "Operation not supported" message when deleting a file:
Answer:     The support for certain very-very rare directory update 
            operations weren't fully tested yet, so they are not 
            included in the release. This is so rare that you probably
	    will never see it ;-)
Workaround: Delete or create other files in the same directory until you
	    can remove the file you originally wanted.
Status:     High priority work.


Problem:    Windows chkdsk complains about free space being marked in use.
Answer:     chkdsk sometimes optimizes the NTFS layout and later finds
            its own bugs (e.g. when index root attributes are moved from 
            extent mft records to the base one). This is not a problem 
	    with ntfs-3g.
Workaround: No need, it's a chkdsk bug and it fixes itself.
Status:     Low priority work: ntfs-3g algorithms will be optimized too.


Problem:    Windows chkdsk reports the below messages (N is a number).
	    Cleaning up N unused index entries from index $SII of file 0x9.
	    Cleaning up N unused index entries from index $SDH of file 0x9.
	    Cleaning up N unused security descriptors.
Answer:     These messages are part of an optimization process which is
	    completely independent of ntfs-3g. Nothing to worry about them.
Workaround: No need.
Status:     Not a driver problem.


Problem:    Windows chkdsk may report minor inconsistency.
Answer:     The allocation size of sparse files isn't set always correctly.
Workaround: No need.
Status:     Normal priority work.


Problem:    Why ntfs-3g CPU usage is always 100%?
Answer:     You have some application running which inefficiently "polls"
            for file modification events.
Workaround: Identify the software and try to upgrade it.
Status:     Normal priority work: CPU usage will be minimized significantly 
	    in the future.

