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

.SH NAME
ntfs_external_attr_find \- find an attribute in the attribute list of an inode
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
int ntfs_external_attr_find  (const ATTR_TYPE \fItype\fB, const ntfschar * \fIname\fB, const u32 \fIname_len\fB, const IGNORE_CASE_BOOL \fIic\fB, const VCN \fIlowest_vcn\fB, const u8 * \fIval\fB, const u32 \fIval_len\fB, ntfs_attr_search_ctx * \fIctx\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fItype\fB\fR
attribute type to find
.TP
\fB\fIname\fB\fR
attribute name to find (optional, i.e. NULL means don't care)
.TP
\fB\fIname_len\fB\fR
attribute name length (only needed if \fIname\fR present)
.TP
\fB\fIic\fB\fR
IGNORE_CASE or CASE_SENSITIVE (ignored if \fIname\fR not present)
.TP
\fB\fIlowest_vcn\fB\fR
lowest vcn to find (optional, non-resident attributes only)
.TP
\fB\fIval\fB\fR
attribute value to find (optional, resident attributes only)
.TP
\fB\fIval_len\fB\fR
attribute value length
.TP
\fB\fIctx\fB\fR
search context with mft record and attribute to search from
.SH "DESCRIPTION"
.PP
You should not need to call this function directly.  Use \fBntfs_attr_lookup\fR
instead.
.PP
Find an attribute by searching the attribute list for the corresponding
attribute list entry.  Having found the entry, map the mft record if the
attribute is in a different mft record/inode, \fBntfs_attr_find\fR the attribute
in there and return it.
.PP
On first search \fIctx\fR->ntfs_ino must be the base mft record and \fIctx\fR must
have been obtained from a call to \fBntfs_attr_get_search_ctx\fR\&.  On subsequent
calls \fIctx\fR->ntfs_ino can be any extent inode, too (\fIctx\fR->base_ntfs_ino is
then the base inode).
.PP
After finishing with the attribute/mft record you need to call
\fBntfs_attr_put_search_ctx\fR to cleanup the search context (unmapping any
mapped inodes, etc).
.PP
If the attribute is found, \fBntfs_external_attr_find\fR returns 0 and
\fIctx\fR->attr will point to the found attribute.  \fIctx\fR->mrec will point to the
mft record in which \fIctx\fR->attr is located and \fIctx\fR->al_entry will point to
the attribute list entry for the attribute.
.PP
If the attribute is not found, \fBntfs_external_attr_find\fR returns -ENOENT and
\fIctx\fR->attr will point to the attribute in the base mft record before which
the attribute being searched for would need to be inserted if such an action
were to be desired.  \fIctx\fR->mrec will point to the mft record in which
\fIctx\fR->attr is located and \fIctx\fR->al_entry will point to the attribute list
entry of the attribute before which the attribute being searched for would
need to be inserted if such an action were to be desired.
.PP
Thus to insert the not found attribute, one wants to add the attribute to
\fIctx\fR->mrec (the base mft record) and if there is not enough space, the
attribute should be placed in a newly allocated extent mft record.  The
attribute list entry for the inserted attribute should be inserted in the
attribute list attribute at \fIctx\fR->al_entry.
.PP
On actual error, \fBntfs_external_attr_find\fR returns -EIO.  In this case
\fIctx\fR->attr is undefined and in particular do not rely on it not changing.