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

.SH NAME
ntfs_attr_find \- find (next) attribute in mft record
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
int ntfs_attr_find  (const ATTR_TYPE \fItype\fB, const ntfschar * \fIname\fB, const u32 \fIname_len\fB, const IGNORE_CASE_BOOL \fIic\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\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
\fBntfs_attr_find\fR takes a search context \fIctx\fR as parameter and searches the
mft record specified by \fIctx\fR->mrec, beginning at \fIctx\fR->attr, for an
attribute of \fItype\fR, optionally \fIname\fR and \fIval\fR\&.
.PP
If the attribute is found, \fBntfs_attr_find\fR returns 0 and \fIctx\fR->attr will
point to the found attribute.
.PP
If the attribute is not found, \fBntfs_attr_find\fR returns -ENOENT and
\fIctx\fR->attr will point to the attribute before which the attribute being
searched for would need to be inserted if such an action were to be desired.
.PP
On actual error, \fBntfs_attr_find\fR returns -EIO.  In this case \fIctx\fR->attr is
undefined and in particular do not rely on it not changing.
.PP
If \fIctx\fR->is_first is TRUE, the search begins with \fIctx\fR->attr itself.  If it
is FALSE, the search begins after \fIctx\fR->attr.
.PP
If \fIic\fR is IGNORE_CASE, the \fIname\fR comparisson is not case sensitive and
\fIctx\fR->ntfs_ino must be set to the ntfs inode to which the mft record
\fIctx\fR->mrec belongs.  This is so we can get at the ntfs volume and hence at
the upcase table.  If \fIic\fR is CASE_SENSITIVE, the comparison is case
sensitive.  When \fIname\fR is present, \fIname_len\fR is the \fIname\fR length in Unicode
characters.
.PP
If \fIname\fR is not present (NULL), we assume that the unnamed attribute is
being searched for.
.PP
Finally, the resident attribute value \fIval\fR is looked for, if present.  If
\fIval\fR is not present (NULL), \fIval_len\fR is ignored.
.PP
\fBntfs_attr_find\fR only searches the specified mft record and it ignores the
presence of an attribute list attribute (unless it is the one being searched
for, obviously).  If you need to take attribute lists into consideration,
use \fBntfs_attr_lookup\fR instead (see below).  This also means that you cannot
use \fBntfs_attr_find\fR to search for extent records of non-resident
attributes, as extents with lowest_vcn != 0 are usually described by the
attribute list attribute only. - Note that it is possible that the first
extent is only in the attribute list while the last extent is in the base
mft record, so do not rely on being able to find the first extent in the
base mft record.
.SH "WARNING"
.PP
Never use \fIval\fR when looking for attribute types which can be
non-resident as this most likely will result in a crash!