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

.SH NAME
ntfs_mapping_pairs_build \- build the mapping pairs array from a runlist
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
int ntfs_mapping_pairs_build  (const ntfs_volume * \fIvol\fB, s8 * \fIdst\fB, const int \fIdst_len\fB, const runlist_element * \fIrl\fB, const VCN \fIfirst_vcn\fB, const VCN \fIlast_vcn\fB, VCN *const \fIstop_vcn\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIvol\fB\fR
ntfs volume (needed for the ntfs version)
.TP
\fB\fIdst\fB\fR
destination buffer to which to write the mapping pairs array
.TP
\fB\fIdst_len\fB\fR
size of destination buffer \fIdst\fR in bytes
.TP
\fB\fIrl\fB\fR
locked runlist for which to build the mapping pairs array
.TP
\fB\fIfirst_vcn\fB\fR
first vcn which to include in the mapping pairs array
.TP
\fB\fIlast_vcn\fB\fR
last vcn which to include in the mapping pairs array
.TP
\fB\fIstop_vcn\fB\fR
first vcn outside destination buffer on success or -ENOSPC
.SH "DESCRIPTION"
.PP
Create the mapping pairs array from the locked runlist \fIrl\fR, starting at vcn
\fIfirst_vcn\fR and finishing with vcn \fIlast_vcn\fR and save the array in \fIdst\fR\&.
\fIdst_len\fR is the size of \fIdst\fR in bytes and it should be at least equal to the
value obtained by calling \fBntfs_get_size_for_mapping_pairs\fR\&.
.PP
A \fIlast_vcn\fR of -1 means end of runlist and in that case the mapping pairs
array corresponding to the runlist starting at vcn \fIfirst_vcn\fR and finishing
at the end of the runlist is created.
.PP
If \fIrl\fR is NULL, just write a single terminator byte to \fIdst\fR\&.
.PP
On success or -ENOSPC error, if \fIstop_vcn\fR is not NULL, *\fIstop_vcn\fR is set to
the first vcn outside the destination buffer.  Note that on error, \fIdst\fR has
been filled with all the mapping pairs that will fit, thus it can be treated
as partial success, in that a new attribute extent needs to be created or
the next extent has to be used and the mapping pairs build has to be
continued with \fIfirst_vcn\fR set to *\fIstop_vcn\fR\&.
.PP
Return 0 on success and -errno on error.  The following error codes are
.SH "DEFINED"
.PP
-EINVAL - Run list contains unmapped elements.  Make sure to only pass
fully mapped runlists to this function.
-EIO - The runlist is corrupt.
-ENOSPC - The destination buffer is too small.
.SH "LOCKING"
.PP
\fIrl\fR must be locked on entry (either for reading or writing), it
remains locked throughout, and is left locked upon return.