.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "NTFS_CLUSTER_ALLOC" "9" "09 October 2005" "" ""

.SH NAME
ntfs_cluster_alloc \- allocate clusters on an ntfs volume
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
runlist_element * ntfs_cluster_alloc  (ntfs_volume * \fIvol\fB, const VCN \fIstart_vcn\fB, const s64 \fIcount\fB, const LCN \fIstart_lcn\fB, const NTFS_CLUSTER_ALLOCATION_ZONES \fIzone\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIvol\fB\fR
mounted ntfs volume on which to allocate the clusters
.TP
\fB\fIstart_vcn\fB\fR
vcn to use for the first allocated cluster
.TP
\fB\fIcount\fB\fR
number of clusters to allocate
.TP
\fB\fIstart_lcn\fB\fR
starting lcn at which to allocate the clusters (or -1 if none)
.TP
\fB\fIzone\fB\fR
zone from which to allocate the clusters
.SH "DESCRIPTION"
.PP
Allocate \fIcount\fR clusters preferably starting at cluster \fIstart_lcn\fR or at the
current allocator position if \fIstart_lcn\fR is -1, on the mounted ntfs volume
\fIvol\fR\&. \fIzone\fR is either DATA_ZONE for allocation of normal clusters or
MFT_ZONE for allocation of clusters for the master file table, i.e. the
\fB$MFT\fR/\fB$DATA\fR attribute.
.PP
\fIstart_vcn\fR specifies the vcn of the first allocated cluster.  This makes
merging the resulting runlist with the old runlist easier.
.PP
You need to check the return value with \fBIS_ERR\fR\&.  If this is false, the
function was successful and the return value is a runlist describing the
allocated cluster(s).  If \fBIS_ERR\fR is true, the function failed and
\fBPTR_ERR\fR gives you the error code.
.PP
Notes on the allocation algorithm
=================================
.PP
There are two data zones.  First is the area between the end of the mft zone
and the end of the volume, and second is the area between the start of the
volume and the start of the mft zone.  On unmodified/standard NTFS 1.x
volumes, the second data zone does not exist due to the mft zone being
expanded to cover the start of the volume in order to reserve space for the
mft bitmap attribute.
.PP
This is not the prettiest function but the complexity stems from the need of
implementing the mft vs data zoned approach and from the fact that we have
access to the lcn bitmap in portions of up to 8192 bytes at a time, so we
need to cope with crossing over boundaries of two buffers.  Further, the
fact that the allocator allows for caller supplied hints as to the location
of where allocation should begin and the fact that the allocator keeps track
of where in the data zones the next natural allocation should occur,
contribute to the complexity of the function.  But it should all be
worthwhile, because this allocator should: 1) be a full implementation of
the MFT zone approach used by Windows NT, 2) cause reduction in
fragmentation, and 3) be speedy in allocations (the code is not optimized
for speed, but the algorithm is, so further speed improvements are probably
possible).
.SH "FIXME"
.PP
We should be monitoring cluster allocation and increment the MFT zone
size dynamically but this is something for the future.  We will just cause
heavier fragmentation by not doing it and I am not even sure Windows would
grow the MFT zone dynamically, so it might even be correct not to do this.
The overhead in doing dynamic MFT zone expansion would be very large and
unlikely worth the effort. (AIA)
.SH "TODO"
.PP
I have added in double the required zone position pointer wrap around
logic which can be optimized to having only one of the two logic sets.
However, having the double logic will work fine, but if we have only one of
the sets and we get it wrong somewhere, then we get into trouble, so
removing the duplicate logic requires _very_ careful consideration of _all_
possible code paths.  So at least for now, I am leaving the double logic -
better safe than sorry... (AIA)
.SH "LOCKING"
.PP
- The volume lcn bitmap must be unlocked on entry and is unlocked
on return.
- This function takes the volume lcn bitmap lock for writing and
modifies the bitmap contents.