.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_match_entries.3in.  The gd_match_entries man page.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_match_entries 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_match_entries \(em search the entry list of a Dirfile

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "unsigned int gd_match_entries(DIRFILE *" dirfile ,
.BI "const char *" regex ", int " fragment ", int " type ,
.BI "unsigned int " flags ", const char ***" entries );
.EC

.SH DESCRIPTION
The
.FN gd_match_entries
function queries a dirfile(5) database specified by
.I dirfile
and all the fields satisfying the provided criteria. If
.I entries
is not NULL, a list of matched entries will be returned in
.BI * entries\fR.

The match criteria are:

.IP \(bu
If
.I regex
is non-NULL, it is a regular expression to match against the entry names.
Various regular expression grammars (or none) may be supported by the library.
See the
.B REGULAR EXPRESSIONS
section below for details.
.IP \(bu
If the
.I fragment
argument is
.BR GD_ALL_FRAGMENTS ,
entries defined in all fragments are matched. Otherwise only entries specified
in the fragment indexed by
.I fragment
are matched.
.IP \(bu
The
.I type
argument should be one of the following symbols indicating an explicit entry
type to match:
.RS
.IP
.SC
.BR GD_BIT_ENTRY ", " GD_CARRAY_ENTRY ", " GD_CONST_ENTRY ", " GD_DIVIDE_ENTRY ,
.BR GD_INDEX_ENTRY ", " GD_INDIR_ENTRY ", " GD_LINCOM_ENTRY ,
.BR GD_LINTERP_ENTRY ", " GD_MPLEX_ENTRY ", " GD_MULTIPLY_ENTRY ,
.BR GD_PHASE_ENTRY ", " GD_POLYNOM_ENTRY ", " GD_RAW_ENTRY ", " GD_RECIP_ENTRY ,
.BR GD_SARRAY_ENTRY ", " GD_SBIT_ENTRY ", " GD_SINDIR_ENTRY ,
.BR GD_STRING_ENTRY ", " GD_WINDOW_ENTRY .
.EC
.PP
.RB ( GD_INDEX_ENTRY
is a special field type for the implicit
.I INDEX
field) or else one of the following special symbols:
.DD "GD_ALL_ENTRIES \fR(=\fB0\fR)"
Match entries of all types.
.DD GD_ALIAS_ENTRIES
Match only aliases.  This is the only way to match aliases which do not point
to valid field codes.
.DD GD_SCALAR_ENTRIES
Match only scalar field types
.RB ( CONST ", " CARRAY ", " SARRAY ", " STRING ).
.DD GD_VECTOR_ENTRIES
Match only numeric-valued vector field types (all field types except
.B SINDIR
and the scalar field types listed above).
.RE
.IP \(bu
The
.I flags
argument should be zero or more of the following flags, bitwise or'd together:
.RS
.DD GD_ENTRIES_HIDDEN
Match hidden entries (see
.F3 gd_hidden ):
normally hidden entries are ignored;
.DD GD_ENTRIES_NOALIAS
Don't match aliases: normally aliases are matched as if they had the entry type
of their target.
.PP
If
.I regex
is non-NULL, these flags may further be bitwise-or'd with the following flags
which affect the interpretation of the supplied regular expression:
.IP
.SC
.BR GD_REGEX_PCRE ", " GD_REGEX_EXTENDED ", " GD_REGEX_ICASE ,
.BR GD_REGEX_CASELESS ", " GD_REGEX_JAVASCRIPT ", " GD_REGEX_UNICODE
.EC
.PP
See the
.B REGULAR EXPRESSIONS
section below for details. If
.I regex
is NULL, these additional regular-expression-specific flags are ignored.
.RE

.SH RETURN VALUE
Upon successful completion,
.FN gd_match_entries
returns the number of entries successfully matched. In this case, if
.I entries
is non-NULL, this function sets
.BI * entries
to a pointer to a list of the matching entry names. This list is terminated by a
NULL pointer. Memory for the list, and for the strings it contains, is managed
by GetData. None of the returned pointers should be free'd by the caller. The
pointers returned are only valid until this function is called again, and the
associated memory will be deallocated when
.I dirfile
is closed (see
.F3 gd_close ).

If no entries match, but no error occurs, zero is returned. In this case, if
.I entries
is non-NULL,
.BI * entries
is still set to a non-NULL pointer, which points to a list containing only the
terminating NULL.

On error, this function also returns zero.  If
.I entries
is non-NULL,
.BI * entries
is set to NULL in this case (which can be used to distinguish this case from the
zero-match case). This function furthermore stores a negative-valued error code
in the
.B DIRFILE
object which may be retrieved by a subsequent call to
.F3 gd_error .
Possible error codes are:
.DD GD_E_ARGUMENT
There was an error in the supplied regular expression. See the
.B REGULAR EXPRESSION
section below for details.
.DD GD_E_BAD_CODE
The supplied parent field code was not found, or referred to a metafield itself.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_ENTRY
The
.I type
parameter supplied was not one of the symbols listed above.
.DD GD_E_UNSUPPORTED
The
.I regex
parameter was non-NULL, but the library lacked support for the specified regular
expression grammar. See the
.B REGULAR EXPRESSION
section below for details.
.PP
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH REGULAR EXPRESSIONS
Regular expression support in GetData is provided by external libraries and is
optional. Whether a particular regular expression library is supported by
GetData is determined when the library is built. Preprocessor symbols are
present in getdata.h to provide compile-time support to programs building
against GetData indicating what support the GetData library was built with.

GetData supports the following regular expression libraries:
.IP \(bu
The POSIX.2 regular expression library, which provides support for both basic
and extended POSIX regular expressions. See regex(7) for details. The POSIX
regular expression library is derived from Henry Spencer's original regex
package found in BSD. If GetData lacks support for POSIX regular expressions,
the symbol
.B GD_NO_REGEX
will be defined in getdata.h.
.IP \(bu
Perl-compatible Regular Expressions (PCRE), which provides a modern,
full-featured regular expression grammar. See pcre(3) for details. If GetData
lacks support for PCREs, the symbol
.B GD_NO_PCRE
will be defined in getdata.h.
.PP
Support for one, both, or neither library may be enabled in the GetData
library when it is built.

When calling
.FN gd_match_entries ,
the choice of regular expression grammar to use is controlled by bitwise-or'ing
.I flags
with zero or more of the following symbols:
.DD GD_REGEX_PCRE
Use the Perl-compatible Regular Expression (PCRE) library for regular expression
matching. Without this flag, the POSIX regex library is used.
.DD GD_REGEX_CASELESS GD_REGEX_ICASE
Perform case-insensitive matching. These two symbols are synonyms. This is
equivalent to the
.B REG_ICASE
flag in
.F3 regex
and the
.B PCRE_CASELESS
flag in
.F3 pcreapi .
.PP
The following flags are only supported when using the PCRE library (i.e., when
.B GD_REGEX_PCRE
is also specified):
.DD GD_REGEX_JAVASCRIPT
Enable Javascript compatibility mode in the PCRE library. This results in a
regular expression grammar that mimics more closely Javascript's regular
expressions than Perl's. See the
.B PCRE_JAVASCRIPT_COMPAT
flag in
.F3 pcreapi
for details.
.DD GD_REGEX_UNICODE
Interpret the supplied regex, as well as the Dirfile's entry names, as UTF-8
sequences. Without this flag, they are all assumed to be ASCII sequences. When
this flag is specified, the flags
.BR PCRE_UTF8
and
.B BPCRE_BSR_UNICODE
are passed to the PCRE library. Without it, the flags
.B PCRE_BSR_ANYCRLF
is used instead. See
.F3 pcreapi
for details.
.PP
In addition to the above, the flags
.B PCRE_DOLLAR_ENDONLY
and
.B PCRE_DOTALL
are always passed to the PCRE library. Note, however, that the PCRE grammar also
permits overriding most of these flags by specifying different options in the
regex pattern itself.

GetData does not return captured substrings to the caller, nor does it support
PCRE callouts.

If the caller attempts to use a regular expression library for which support has
not been built into GetData,
.B GD_E_UNSUPPORTED
will be returned. It is always possible for the caller avoid this error at
runtime by checking for
.B GD_NO_REGEX
or
.B GD_NO_PCRE
at compile time.

Errors returned by the regular expression compiler itself will be reported to
the caller with
.BR GD_E_ARGUMENT .

.SH HISTORY
The
.FN gd_match_entries
function appeared in GetData-0.10.0.

.SH SEE ALSO
.F3 gd_entry_list ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_hidden ,
.F3 gd_match_entries ,
.F3 gd_nentries ,
.F3 gd_open ,
dirfile(5)