.\" 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_RUNLISTS_MERGE" "9" "09 October 2005" "" ""

.SH NAME
ntfs_runlists_merge \- merge two runlists into one
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
runlist_element * ntfs_runlists_merge  (runlist_element * \fIdrl\fB, runlist_element * \fIsrl\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIdrl\fB\fR
original runlist to be worked on
.TP
\fB\fIsrl\fB\fR
new runlist to be merged into \fIdrl\fR
.SH "DESCRIPTION"
.PP
First we sanity check the two runlists \fIsrl\fR and \fIdrl\fR to make sure that they
are sensible and can be merged. The runlist \fIsrl\fR must be either after the
runlist \fIdrl\fR or completely within a hole (or unmapped region) in \fIdrl\fR\&.
.PP
It is up to the caller to serialize access to the runlists \fIdrl\fR and \fIsrl\fR\&.
.SH "MERGING OF RUNLISTS IS NECESSARY IN TWO CASES"
.PP
1. When attribute lists are used and a further extent is being mapped.
2. When new clusters are allocated to fill a hole or extend a file.
.PP
There are four possible ways \fIsrl\fR can be merged. It can:
- be inserted at the beginning of a hole,
- split the hole in two and be inserted between the two fragments,
- be appended at the end of a hole, or it can
- replace the whole hole.
It can also be appended to the end of the runlist, which is just a variant
of the insert case.
.PP
On success, return a pointer to the new, combined, runlist. Note, both
runlists \fIdrl\fR and \fIsrl\fR are deallocated before returning so you cannot use
the pointers for anything any more. (Strictly speaking the returned runlist
may be the same as \fIdst\fR but this is irrelevant.)
.PP
On error, return -errno. Both runlists are left unmodified. The following
.SH "ERROR CODES ARE DEFINED"
.PP
-ENOMEM - Not enough memory to allocate runlist array.
-EINVAL - Invalid parameters were passed in.
-ERANGE - The runlists overlap and cannot be merged.