.\" 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 "MAP_MFT_RECORD" "" "06 October 2005" "" ""

.SH NAME
map_mft_record \- map, pin and lock an mft record
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
MFT_RECORD * map_mft_record  (ntfs_inode * \fIni\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIni\fB\fR
ntfs inode whose MFT record to map
.SH "DESCRIPTION"
.PP
First, take the mrec_lock semaphore. We might now be sleeping, while waiting
for the semaphore if it was already locked by someone else.
.PP
The page of the record is mapped using \fBmap_mft_record_page\fR before being
returned to the caller.
.PP
This in turn uses \fBntfs_map_page\fR to get the page containing the wanted mft
record (it in turn calls \fBread_cache_page\fR which reads it in from disk if
necessary, increments the use count on the page so that it cannot disappear
under us and returns a reference to the page cache page).
.PP
If \fBread_cache_page\fR invokes \fBntfs_readpage\fR to load the page from disk, it
sets PG_locked and clears PG_uptodate on the page. Once I/O has completed
and the post-read mst fixups on each mft record in the page have been
performed, the page gets PG_uptodate set and PG_locked cleared (this is done
in our asynchronous I/O completion handler \fBend_buffer_read_mft_async\fR).
\fBntfs_map_page\fR waits for PG_locked to become clear and checks if
PG_uptodate is set and returns an error code if not. This provides
sufficient protection against races when reading/using the page.
.PP
However there is the write mapping to think about. Doing the above described
checking here will be fine, because when initiating the write we will set
PG_locked and clear PG_uptodate making sure nobody is touching the page
contents. Doing the locking this way means that the commit to disk code in
the page cache code paths is automatically sufficiently locked with us as
we will not touch a page that has been locked or is not uptodate. The only
locking problem then is them locking the page while we are accessing it.
.PP
So that code will end up having to own the mrec_lock of all mft
records/inodes present in the page before I/O can proceed. In that case we
wouldn't need to bother with PG_locked and PG_uptodate as nobody will be
accessing anything without owning the mrec_lock semaphore. But we do need
to use them because of the \fBread_cache_page\fR invocation and the code becomes
so much simpler this way that it is well worth it.
.PP
The mft record is now ours and we return a pointer to it. You need to check
the returned pointer with \fBIS_ERR\fR and if that is true, \fBPTR_ERR\fR will return
the error code.
.SH "NOTE"
.PP
Caller is responsible for setting the mft record dirty before calling
\fBunmap_mft_record\fR\&. This is obviously only necessary if the caller really
modified the mft record...
.SH "Q"
.PP
Do we want to recycle one of the VFS inode state bits instead?
.SH "A"
.PP
No, the inode ones mean we want to change the mft record, not we want to
write it out.