Normally, when you want to perform a file system query, you would use the
BQuery
class,
which is a nice, clean, object-oriented way to do it. If
you have an aversion to object-oriented programming, however, or you're
writing a simple C program and would rather use C functions instead, then
you've come to the right place.
Be aware that, currently, you can't perform "live" queries at the C
level. If you want a live query, you have to use a
BQuery
object.
To begin a query, you call
fs_open_query()
.
fs_open_query()
performs a
"one-shot" query: It lets you ask for all the files that fulfill certain
criteria right now. This criteria is expressed as a "predicate" string.
This is a formula that lists the attribute values that you're interested
in. A simple predicate takes the form
attribute op value
For example, you can look for files that are larger than 5K by supplying a string that looks like this:
"size > 5000"
Simple predicates can be grouped and combined to create more complex predicates. Here we look for files named "fido" that are greater than 5K:
"(name = fido) && (size > 5000)"
For a full description of the predicate format, see
"The Predicate, Attributes, and Indices" in the
BQuery
class
description, but be aware of this difference:
The fs_query
functions don't let you "push" elements onto the
predicate; all predicates must be expressed as strings.
Once the query has been opened, you can step through the files that
fulfill the predicate through iterated calls to
fs_read_query()
. When all
the winning files have been visited,
fs_read_query()
returns NULL
.
When you've finished using your query, you must close it by using the
fs_close_query()
function.
The following sample demonstrates very briefly how to perform a simple, non-live query. In this example, we're searching for all C header files on the device specified by devnum.
voidsample_query
(dev_tdevnum
) { DIR*q
; dirent_t*d
;q
=fs_open_query
(devnum
, "name=*.h", 0); if (q
) { while (d
=fs_read_query
(q
)) { ... }fs_close_query
(q
); } }
The code opens the query by calling
fs_open_query()
, then, calls
fs_read_query()
in a loop until NULL
is returned. Once that happens,
fs_close_query()
is used to close the query.