PenTest/nmap
1
0
Fork 0
mirror of https://github.com/nmap/nmap.git synced 2025-12-15 04:09:01 +00:00
Code Issues Projects Releases Wiki Activity

Add luadoc files for openssl and pcre. That finishes the modules in the section

Browse Source 
"Lua Extensions", which is now just a stub.
This commit is contained in:
david
2008-10-16 04:08:53 +00:00
parent 99c30b1d1b
commit c30776fec7
3 changed files with 228 additions and 452 deletions
Download Patch File Download Diff File Expand all files Collapse all files

453
docs/scripting.xml
View File

@@ -763,7 +763,7 @@ action refer to <xref linkend="nse-tutorial-action"/>.
</sect2>
</sect1>
<sect1 id="nse-library">
<indexterm class="startofrange" id="nse-library-indexterm"><primary>Nmap Scripting Engine (NSE)</primary><secondary>modules</secondary></indexterm>
<indexterm><primary>Nmap Scripting Engine (NSE)</primary><secondary>modules</secondary></indexterm>
<title>Lua Extensions</title>
<para>In addition to the significant built-in capabilities of
Lua, we have written or integrated several extensions to make
@@ -774,458 +774,7 @@ action refer to <xref linkend="nse-tutorial-action"/>.
<ulink url="http://www.lua.org/manual/5.1/manual.html#pdf-require">
<literal>require</literal>
</ulink> the default modules in order to use them.
The default modules are described in the following sections.
</para>
<sect2 id="nse-pcre">
<indexterm class="startofrange" id="nse-pcre-indexterm"><primary><varname>pcre</varname> NSE module</primary></indexterm>
<indexterm><primary>Perl Compatible Regular Expressions (PCRE)</primary><secondary>in NSE</secondary></indexterm>
<indexterm><primary>regular expressions</primary><secondary>in NSE</secondary></indexterm>
<title>Perl Compatible Regular Expressions</title>
<para>
One of Lua's quirks is its string patterns. While they have
great performance and are tightly integrated into the Lua
interpreter, they are very different in syntax and not as
powerful as standard regular expressions. So we have
integrated Perl compatible regular expressions into Lua
using PCRE and a modified version of the Lua PCRE library
written by Reuben Thomas<indexterm><primary>Thomas, Reuben</primary></indexterm>
and Shmuel Zeigerman.<indexterm><primary>Zeigerman, Shmuel</primary></indexterm>
These are
the same sort of regular expressions used by Nmap version
detection. The main modification to their library is that
the NSE version only supports PCRE expressions instead of both
PCRE and POSIX patterns. In order to maintain a high script
execution speed, the library interfacing with PCRE is
kept very thin. It is not integrated as seamlessly as the
Lua string pattern API. This allows script authors to decide
when to use PCRE expressions versus Lua patterns. The use of PCRE
involves a separate pattern compilation step, which saves
execution time when patterns are reused. Compiled patterns
can be cached in the NSE registry and reused by other
scripts. The PCRE functions reside inside the <literal>pcre</literal>
namespace.
</para>
<indexterm><primary>Perl Compatible Regular Expressions (PCRE)</primary><secondary>security vulnerabilities in</secondary></indexterm>
<warning><para>PCRE has a history of security vulnerabilities
allowing attackers who are able to compile arbitrary regular
expressions to execute arbitrary code. More such
vulnerabilities may be discovered in the future. These have
never affected Nmap because it doesn't give attackers any
control over the regular expressions it uses. Similarly, NSE
scripts should never build regular expressions with untrusted
network input. Matching hardcoded regular expressions
<emphasis>against</emphasis> the untrusted input is
fine.</para></warning>
<para>The following documentation is derived from that supplied by
the PCRE Lua lib.</para>
<variablelist>
<varlistentry>
<term><option>pcre.new(pattern, flags, locale)</option>
</term>
<listitem>
<para>
Returns a compiled regular expression. The first
argument is a string describing the pattern, such as
<literal>^foo$</literal>. The second
argument is a number describing which compilation
flags are set. The compilation flags are set
bitwise. If you want to set the 3rd (corresponding to
the number 4) and the 1st (corresponding to 1) bit
for example you would pass the number 5 as a second
argument. The compilation flags accepted are those
of the PCRE C library. These include flags for case
insensitive matching (1), matching line beginnings (^)
and endings ($) even in multiline strings (i.e. strings
containing <quote>\n</quote>) (2) and a flag for matching across
line boundaries (4). No compilation flags yield a default
value of 0. The third (optional) argument is a string
describing the locale which should be used to compile the
regular expression. The variable is a string which is
passed to the C standard library function
<function>setlocale</function>. For more
information on this argument refer to the
documentation of <function>setlocale</function>. The
resulting compiled regular expression is ready to be
matched against strings. Compiled regular
expressions are subject to Lua's garbage collection.
Generally speaking, <literal>my_regex = pcre.new("<replaceable>pcre-pattern</replaceable>",0,"C")</literal>
should do the job most of the time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pcre.flags()</option>
</term>
<listitem>
<para>
Returns a table of the available PCRE option flags
(numbers) keyed by their names (strings). Possible
names of the available strings can be retrieved from
the documentation of the PCRE library used to link
against Nmap. The key is the option name in the
manual minus the <literal>PCRE</literal>
prefix. <literal>PCRE_CASELESS</literal> becomes
<literal>CASELESS</literal> for example.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pcre.version()</option>
</term>
<listitem>
<para>
Returns the version of the PCRE library in use as a
string. For example <literal>6.4 05-Sep-2005</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pcre_obj:match(string, start, flags)</option>
</term>
<listitem>
<para>
Returns the start point and the end point of
the first match of the compiled regular expression
pcre_obj in the string. A third
returned value is a table which contains
<literal>false</literal> in the positions where the
pattern did not match. If named sub-patterns were
used, the table also contains substring matches keyed
by their sub-pattern name. Should no match be found the
function returns <literal>nil</literal>.
The second and third arguments are optional. The second
argument is a number specifying where the engine should
start trying to apply the pattern. The third argument
specifies execution flags for the pattern.
If you want to see if a given string matches a certain expression
you could use:</para>
<programlisting>
s = pcre_obj:match("string to be searched", 0,0);
if(s) code_to_be_done_on_match end
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pcre_obj:exec(string, start, flags)</option>
</term>
<listitem>
<para>
This function is like <literal>match()</literal> except that a table returned as
a third result contains offsets of substring matches rather
than substring matches themselves. That table will not
contain string keys, even if named sub-patterns are used. For
example, if the whole match is at offsets <literal>10, 20</literal> and substring
matches are at offsets <literal>12, 14</literal> and <literal>16, 19</literal> then the function
returns the following: <literal>10, 20, {12,14,16,19}</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>pcre_obj:gmatch(string, func, n, ef)</option>
</term>
<listitem>
<para>
Tries to match the regular expression <replaceable>pcre_obj</replaceable> against <replaceable>string</replaceable>
up to <replaceable>n</replaceable> times (or as many as possible if <replaceable>n</replaceable> is either
not given or is not a positive number), subject to
execution flags ef. Each time there is a match, <replaceable>func</replaceable>
is called as <replaceable>func(m, t)</replaceable>, where <replaceable>m</replaceable> is the matched
string and <replaceable>t</replaceable> is a table of substring matches. This
table contains <literal>false</literal> in the
positions where the corresponding sub-pattern did
not match. If named sub-patterns are used then the
table also contains substring matches keyed by their
correspondent sub-pattern names (strings). If <replaceable>func</replaceable>
returns a <literal>true</literal> value, then gmatch
immediately returns; gmatch returns the number of
matches made.
</para>
</listitem>
</varlistentry>
</variablelist>
<indexterm class="endofrange" startref="nse-pcre-indexterm"/>
</sect2>
<sect2 id="nse-openssl">
<indexterm class="startofrange" id="nse-openssl-indexterm"><primary><varname>openssl</varname> NSE module</primary></indexterm>
<indexterm><primary>OpenSSL</primary><seealso><varname>openssl</varname> NSE module</seealso></indexterm>
<indexterm><primary>OpenSSL</primary><secondary>in NSE</secondary></indexterm>
<title>OpenSSL NSE bindings</title>
<para>
The <literal>openssl</literal> module is a wrapper for OpenSSL
functions that provide encryption and decryption, hashing, and
multiprecision integers.
</para>
<variablelist>
<varlistentry>
<term><option>openssl.bignum_num_bits(bignum)</option></term>
<listitem>
<para>Returns the size of <literal>bignum</literal> in bits.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_num_bytes(bignum)</option></term>
<listitem>
<para>Returns the size of <literal>bignum</literal> in bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_set_bit(bignum, position)</option></term>
<listitem>
<para>Sets the bit at <literal>position</literal> in <literal>bignum</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_clear_bit(bignum, position)</option></term>
<listitem>
<para>Clears the bit at <literal>position</literal> in <literal>bignum</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_is_bit_set(bignum, position)</option></term>
<listitem>
<para>Gets the state of the bit at <literal>position</literal> in <literal>bignum</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_set_negative(bignum, negative)</option></term>
<listitem>
<para>Sets the sign of <literal>bignum</literal>. If
<literal>negative</literal> is <literal>true</literal>
the sign becomes negative, otherwise it becomes positive.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_is_negative(bignum)</option></term>
<listitem>
<para>Returns true if <literal>bignum</literal> is
negative, false otherwise.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_bin2bn(string)</option></term>
<listitem>
<para>Converts the binary-encoded <literal>string</literal> into a <literal>bignum</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_dec2bn(string)</option></term>
<listitem>
<para>Converts the decimal-encoded <literal>string</literal> into a <literal>bignum</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_hex2bn(string)</option></term>
<listitem>
<para>Converts the hex-encoded <literal>string</literal> into a <literal>bignum</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_bn2bin(bignum)</option></term>
<listitem>
<para>Converts <literal>bignum</literal> into a binary-encoded string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_bn2dec(bignum)</option></term>
<listitem>
<para>Converts <literal>bignum</literal> into a decimal-encoded string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_bn2hex(bignum)</option></term>
<listitem>
<para>Converts <literal>bignum</literal> into a hex-encoded string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_rand(bits)</option></term>
<listitem>
<para>Returns a random <literal>bignum</literal> with a
size of <literal>bits</literal> bits.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_pseudo_rand(bits)</option></term>
<listitem>
<para>Returns a pseudorandom <literal>bignum</literal>
with a size of <literal>bits</literal> bits.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.bignum_mod_exp(a, p, m)</option></term>
<listitem>
<para>Returns the bignum which is the result of <literal>a</literal>^<literal>p</literal> mod <literal>m</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.rand_bytes(bytes)</option></term>
<listitem>
<para>Returns a string of length
<literal>bytes</literal> containing random data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.rand_pseudo_bytes(bytes)</option></term>
<listitem>
<para>Returns a string of length
<literal>bytes</literal> containing pseudorandom data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary>digests, cryptographic</primary></indexterm>
<indexterm><primary>hashes, cryptographic</primary></indexterm>
<option>openssl.md2(message)</option></term>
<listitem>
<para>Returns the MD2 digest of <literal>message</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.md4(message)</option></term>
<listitem>
<para>Returns the MD4 digest of <literal>message</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.md5(message)</option></term>
<listitem>
<para>Returns the MD5 digest of <literal>message</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.sha1(message)</option></term>
<listitem>
<para>Returns the SHA-1 digest of <literal>message</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.ripemd160(message)</option></term>
<listitem>
<para>Returns the RIPEMD-160 digest of <literal>message</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.digest(algorithm, message)</option></term>
<listitem>
<para>Returns the digest of <literal>message</literal>
using the algorithm given by the string
<literal>algorithm</literal>. The algorithm name may be
anything returned by the
<function>openssl.supported_digests</function>
function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.hmac(algorithm, key, message)</option></term>
<listitem>
<para>Returns the message authentication code of
<literal>message</literal> using the given algorithm and
key. <literal>algorithm</literal> may be anything
returned by the
<function>openssl.supported_digests</function>
function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary>keys, cryptographic</primary></indexterm>
<option>openssl.encrypt(algorithm, key, iv, data, padding = false)</option></term>
<listitem>
<para>Encrypt <literal>data</literal> with the given
algorithm, key, and initialization vector.
<literal>algorithm</literal> may be anything
returned by the
<function>openssl.supported_ciphers</function>
function. If <literal>padding</literal> is true then a
partial final block will be padded and encrypted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.decrypt(algorithm, key, iv, data, padding = false)</option></term>
<listitem>
<para>Encrypt <literal>data</literal> with the given
algorithm, key, and initialization vector.
<literal>algorithm</literal> may be anything
returned by the
<function>openssl.supported_ciphers</function>
function. If <literal>padding</literal> is true then the
final block must be padded correctly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.supported_ciphers()</option></term>
<listitem>
<para>Returns a table with the names of the supported cipher algorithms.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.supported_digests()</option></term>
<listitem>
<para>Returns a table with the names of the supported digest algorithms.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>openssl.DES_string_to_key(string data)</option></term>
<listitem>
<para>Converts <literal>data</literal>, which must be a
7-byte string, into an 8-byte DES key and sets the
parity.</para>
</listitem>
</varlistentry>
</variablelist>
<indexterm class="endofrange" startref="nse-openssl-indexterm"/>
</sect2>
<indexterm class="endofrange" startref="nse-library-indexterm"/>
</sect1>
<sect1 id="nse-api">

108
nselib/openssl.luadoc Normal file
View File

@@ -0,0 +1,108 @@
--- OpenSSL bindings.
-- \n\n
-- This module is a wrapper for OpenSSL functions that provide encryption and
-- decryption, hashing, and multiprecision integers.
-- @author Sven Klemm <sven@c3d2.de>
-- @copyright See nmaps COPYING for licence
module "openssl"
--- Returns the size of bignum in bits.
function openssl.bignum_num_bits(bignum)
--- Returns the size of bignum in bytes.
function openssl.bignum_num_bytes(bignum)
--- Sets the bit at position in bignum.
function openssl.bignum_set_bit(bignum, position)
--- Clears the bit at position in bignum.
function openssl.bignum_clear_bit(bignum, position)
--- Gets the state of the bit at position in bignum.
function openssl.bignum_is_bit_set(bignum, position)
--- Sets the sign of bignum. If negative is true the sign becomes negative,
-- otherwise it becomes positive.
function openssl.bignum_set_negative(bignum, negative)
--- Returns true if bignum is negative, false otherwise.
function openssl.bignum_is_negative(bignum)
--- Converts the binary-encoded string into a bignum.
function openssl.bignum_bin2bn(string)
--- Converts the decimal-encoded string into a bignum.
function openssl.bignum_dec2bn(string)
--- Converts the hex-encoded string into a bignum.
function openssl.bignum_hex2bn(string)
--- Converts bignum into a binary-encoded string.
function openssl.bignum_bn2bin(bignum)
--- Converts bignum into a decimal-encoded string.
function openssl.bignum_bn2dec(bignum)
--- Converts bignum into a hex-encoded string.
function openssl.bignum_bn2hex(bignum)
--- Returns a random bignum with a
function openssl.bignum_rand(bits)
--- Returns a pseudorandom bignum with a the given size in bits.
function openssl.bignum_pseudo_rand(bits)
--- Returns the bignum which is the result of a^p mod m.
function openssl.bignum_mod_exp(a, p, m)
--- Returns a string of length bytes containing random data.
function openssl.rand_bytes(bytes)
--- Returns a string of length bytes containing pseudorandom data.
function openssl.rand_pseudo_bytes(bytes)
--- Returns the MD2 digest of message.
function openssl.md2(message)
--- Returns the MD4 digest of message.
function openssl.md4(message)
--- Returns the MD5 digest of message.
function openssl.md5(message)
--- Returns the SHA-1 digest of message.
function openssl.sha1(message)
--- Returns the RIPEMD-160 digest of message.
function openssl.ripemd160(message)
--- Returns the digest of message using the algorithm given by the string
-- algorithm. The algorithm name may be anything returned by the
-- openssl.supported_digests function.
function openssl.digest(algorithm, message)
--- Returns the message authentication code of message using the given algorithm
-- and key. algorithm may be anything returned by the openssl.supported_digests
-- function.
function openssl.hmac(algorithm, key, message)
--- Encrypt data with the given algorithm, key, and initialization vector.
-- algorithm may be anything returned by the openssl.supported_ciphers function.
-- If padding is true then a partial final block will be padded and encrypted.
function openssl.encrypt(algorithm, key, iv, data, padding = false)
--- Encrypt data with the given algorithm, key, and initialization vector.
-- algorithm may be anything returned by the openssl.supported_ciphers function.
-- If padding is true then the final block must be padded correctly.
function openssl.decrypt(algorithm, key, iv, data, padding = false)
--- Returns a table with the names of the supported cipher algorithms.
function openssl.supported_ciphers()
--- Returns a table with the names of the supported digest algorithms.
function openssl.supported_digests()
--- Converts data, which must be a 7-byte string, into an 8-byte DES key and
-- sets the parity.
function openssl.DES_string_to_key(string data)

119
nselib/pcre.luadoc Normal file
View File

@@ -0,0 +1,119 @@
--- Perl Compatible Regular Expressions
-- \n\n
-- One of Lua's quirks is its string patterns. While they have great performance
-- and are tightly integrated into the Lua interpreter, they are very different
-- in syntax and not as powerful as standard regular expressions. So we have
-- integrated Perl compatible regular expressions into Lua using PCRE and a
-- modified version of the Lua PCRE library written by Reuben Thomas and Shmuel
-- Zeigerman. These are the same sort of regular expressions used by Nmap
-- version detection. The main modification to their library is that the NSE
-- version only supports PCRE expressions instead of both PCRE and POSIX
-- patterns. In order to maintain a high script execution speed, the library
-- interfacing with PCRE is kept very thin. It is not integrated as seamlessly
-- as the Lua string pattern API. This allows script authors to decide when to
-- use PCRE expressions versus Lua patterns. The use of PCRE involves a
-- separate pattern compilation step, which saves execution time when patterns
-- are reused. Compiled patterns can be cached in the NSE registry and reused
-- by other scripts.
-- \n\n
-- The documentation for this module is derived from that supplied by the PCRE
-- Lua lib.
-- \n\n
-- Warning: PCRE has a history of security vulnerabilities allowing attackers
-- who are able to compile arbitrary regular expressions to execute arbitrary
-- code. More such vulnerabilities may be discovered in the future. These have
-- never affected Nmap because it doesn't give attackers any control over the
-- regular expressions it uses. Similarly, NSE scripts should never build
-- regular expressions with untrusted network input. Matching hardcoded regular
-- expressions against the untrusted input is fine.
-- @author Reuben Thomas
-- @author Shmuel Zeigerman
module "pcre"
--- Returns a compiled regular expression.
-- \n\n
-- The resulting compiled regular expression is ready to be matched against
-- strings. Compiled regular expressions are subject to Lua's garbage
-- collection.
-- \n\n
-- The compilation flags are set bitwise. If you want to set the 3rd
-- (corresponding to the number 4) and the 1st (corresponding to 1) bit for
-- example you would pass the number 5 as a second argument. The compilation
-- flags accepted are those of the PCRE C library. These include flags for case
-- insensitive matching (1), matching line beginnings (^) and endings ($) even
-- in multiline strings (i.e. strings containing newlines) (2) and a flag for
-- matching across line boundaries (4). No compilation flags yield a default
-- value of 0.
-- @param pattern a string describing the pattern, such as "^foo$".
-- @param flags a number describing which compilation flags are set.
-- @param locale a string describing the locale which should be used to compile
-- the regular expression (optional). The value is a string which is passed to
-- the C standard library function setlocale. For more information on this
-- argument refer to the documentation of setlocale.
-- @usage my_regex = pcre.new("pcre-pattern",0,"C")
function pcre.new(pattern, flags, locale)
--- Returns a table of the available PCRE option flags (numbers) keyed by their
-- names (strings).
-- \n\n
-- Possible names of the available strings can be retrieved from the
-- documentation of the PCRE library used to link against Nmap. The key is the
-- option name in the manual minus the PCRE prefix. PCRE_CASELESS becomes
-- CASELESS for example.
function pcre.flags()
--- Returns the version of the PCRE library in use as a string.
-- \n\n
-- For example "6.4 05-Sep-2005".
function pcre.version()
--- Matches a string against a compiled regular expression.
-- \n\n
-- Returns the start point and the end point of the first match of the compiled
-- regular expression pcre_obj in the string.
-- @param string the string to match against.
-- @param start where to start the match in the string (optional).
-- @param flags execution flags (optional).
-- @return nil if no match, otherwise the start point of the first match.
-- @return the end point of the first match.
-- @return a table which contains false in the positions where the pattern did
-- not match. If named sub-patterns were used, the table also contains substring
-- matches keyed by their sub-pattern name.
-- @usage
-- s = pcre_obj:match("string to be searched", 0,0);\n
-- if(s) code_to_be_done_on_match end
function pcre_obj:match(string, start, flags)
--- Matches a string against a compiled regular expression, returning positions
-- of substring matches.
-- \n\n
-- This function is like match() except that a table returned as a third result
-- contains offsets of substring matches rather than substring matches
-- themselves. That table will not contain string keys, even if named
-- sub-patterns are used. For example, if the whole match is at offsets 10, 20
-- and substring matches are at offsets 12, 14 and 16, 19 then the function
-- returns the following: 10, 20, {12,14,16,19}
-- @param string the string to match against.
-- @param start where to start the match in the string (optional).
-- @param flags execution flags (optional).
-- @return a table which contains a list of substring match start and end
-- positions.
function pcre_obj:exec(string, start, flags)
--- Matches a string against a regular expression multiple times.
-- \n\n
-- Tries to match the regular expression pcre_obj against string up to n times
-- (or as many as possible if n is either not given or is not a positive
-- number), subject to the execution flags ef. Each time there is a match, func
-- is called as func(m, t), where m is the matched string and t is a table of
-- substring matches. This table contains false in the positions where the
-- corresponding sub-pattern did not match. If named sub-patterns are used then
-- the table also contains substring matches keyed by their correspondent
-- sub-pattern names (strings). If func returns a true value, then gmatch
-- immediately returns; gmatch returns the number of matches made.
-- @param string the string to match against.
-- @param n the maximum number of matches to do (optional).
-- @param ef execution flags (optional).
-- @return the number of matches made.
function pcre_obj:gmatch(string, func, n, ef)