正文
示例位置: <hyperscan source>/examples/simplegrep.c
参考:http://01org.github.io/hyperscan/dev-reference/api_files.html
1. 概述
此示例实现一个grep的简化版本:指定一个正则表达式和文件,执行后依次输出匹配位置。
但这个简单示例并不支持从stdin读取数据,也不支持grep那丰富的命令行参数。
simplegrep演示了以下hyperscan概念:
- 单个模式的编译
使用最简单的hs_compile接口,仅支持一个正则表达式。支持多个表达式同时编译的API是hs_compile_multi - Block方式的模式匹配
在单个数据块上进行搜索匹配;更复杂的是在流(stream)上进行匹配,它可以跨数据块进行模式匹配 - 临时数据(scratch)的分配与使用
hyperscan在匹配时需要一块临时数据(记为D),调用者需要保证在同一时刻只有一个hs_scan接口使用同一D,但并不要求连续的hs_can调用必须使用同一个D。由于D的分配代价昂贵,为了性能考虑,用户最好在运行前就分配好D并在运行时重用它。
2. 源码解读
这个示例非常简单,这里只解读表达式编译和匹配两部分的代码,读取数据文件等代码忽略。
2.1 编译正则表达式(compile)
进行匹配之前,首先需要编译正则表达式,生成hs_database_t。
hs_database_t *database; hs_compile_error_t *compile_err; if (hs_compile(pattern, HS_FLAG_DOTALL, HS_MODE_BLOCK, NULL, &database, &compile_err) != HS_SUCCESS) { fprintf(stderr, "ERROR: Unable to compile pattern \"%s\": %s\n", pattern, compile_err->message); hs_free_compile_error(compile_err); return -1; }
hs_compile的原型是
hs_error_t hs_compile(const char * expression,
unsigned int flags,
unsigned int mode,
const hs_platform_info_t * platform,
hs_database_t ** db,
hs_compile_error_t ** error)
其中,expression是正则表达式字符串;flags用来控制正则的行为,比如忽略大小写,使.包含换行等;mode确定了生成database的格式,主要有BLOCK,STREAM和VECTOR三种,每一种模式的database只能由相应的scan接口使用;platform用来指定此database的目标平台(主要是一些CPU特性),为NULL表示目标平台与当前平台一致;db用来保存编译后的database;error接收错误信息。
2.2 进行匹配(scan)
首先分配好每次匹配需要用的临时数据(scratch)。
hs_scratch_t *scratch = NULL; if (hs_alloc_scratch(database, &scratch) != HS_SUCCESS) { fprintf(stderr, "ERROR: Unable to allocate scratch space. Exiting.\n"); free(inputData); hs_free_database(database); return -1; }
接下来进行匹配(scan)。
if (hs_scan(database, inputData, length, 0, scratch, eventHandler, pattern) != HS_SUCCESS) { fprintf(stderr, "ERROR: Unable to scan input buffer. Exiting.\n"); hs_free_scratch(scratch); free(inputData); hs_free_database(database); return -1; }
hs_scan的原型是
hs_error_t hs_scan(const hs_database_t * db,
const char * data,
unsigned int length,
unsigned int flags,
hs_scratch_t * scratch,
match_event_handler onEvent,
void * context)
其中,db就是上一步编译的databas;data和length分别是要匹配的数据和数据长度;flags用来在未来版本中控制函数行为,目前未使用;scratch是匹配时要用的临时数据,之前已经分配好;onEvent非常关键,即匹配时调用的回调函数,由用户指定;context是用户自定义指针。
匹配回调函数的原型是
typedef (* match_event_handler)(unsigned int id,
unsigned long long from,
unsigned long long to,
unsigned int flags,
void *context)
其中,id是命中的正则表达式的ID,对于使用hs_compile编译的唯一表达式来说,此值为0;如果在编译时指定了相关模式选项(hs_compile中的mode参数),则此值将会设为匹配特征的起始位置,否则会设为0;to是命中数据的下一个字节的偏移;flags目前未用;context是用户自定义指针。
返回值为非0表示停止匹配,否则继续;在匹配的过程中,每次命中时都将同步调用匹配回调函数,直到匹配结束。
本例中的回调函数是
static int eventHandler(unsigned int id, unsigned long long from, unsigned long long to, unsigned int flags, void *ctx) { printf("Match for pattern \"%s\" at offset %llu\n", (char *)ctx, to); return 0; }
输出了正则表达式和其匹配的位置(命中数据的下一个字节在数据中的偏移值)。
2.3 清理资源
程序结束后,应清理相关数据,释放内存。
hs_free_scratch(scratch); free(inputData); hs_free_database(database);
3. 编译运行
编译之前,我已经通过make install将hyperscan头文件和静态库安装在了/usr/local相关目录中。
gcc -o simplegrep simplegrep.c -lhs -lstdc++ -lm
注意链接stdc++和math库 (lstdc++ -lm)。如果是链接动态库,不需要加-lstdc++ -lm。
运行,在另一示例代码pcapscan.cc中匹配/[f|F]ile/:
./simplegrep '[f|F]ile' pcapscan.cc Scanning 22859 bytes with Hyperscan Match for pattern "[f|F]ile" at offset 1692 .....(略,共45次匹配)
用grep命令验证结果
grep -o '[f|F]ile' pcapscan.cc | wc -l 45
OK,也是45次。